Doc fixes, clean up cross-line single tick code snippets.

Author: rspeele

DEVELOPER_README.md

@@ -5,13 +5,12 @@ Notes for working on this repo.
 ## Prerequisites
 
 - .NET SDK 10 or newer
-- PowerShell 5.1+ on Windows; PowerShell 7+ on Linux/macOS (install: <https://learn.microsoft.com/powershell/scripting/install/installing-powershell>). The build scripts (`build/pack-dev.ps1`, `build/pack-release.ps1`) are pwsh-only.
+- PowerShell 5.1+ on Windows; PowerShell 7+ on Linux/macOS (install: <https://learn.microsoft.com/powershell/scripting/install/installing-powershell>). The build scripts (`build/pack-dev.ps1`, `build/pack-release.ps1`) use PowerShell.
 
 ## Repo layout assumption
 
-The dev workflow assumes you have this repo cloned alongside its sibling
-repos (most importantly [Rezoom](https://github.com/rspeele/Rezoom)) under a
-common parent directory. The parent's name doesn't matter, but the
+The dev workflow assumes you have this repo cloned alongside its sibling repos (most importantly
+[Rezoom](https://github.com/rspeele/Rezoom)) under a common parent directory. The parent's name doesn't matter, but the
 siblings need to be together.
 
 ```
@@ -38,39 +37,22 @@ You need a `NuGet.config` at the parent level so package restore finds
 </configuration>
 ```
 
-If you're only working on Rezoom.SQL and don't need to iterate on Rezoom,
-you can use the latest published Rezoom from nuget.org. If you're changing
-both, pack Rezoom into the same `.localfeed` first using whatever script that
-repo provides.
+This allows pushing local "updates" to the NuGet packages so the TypeProviderUser tests can reference them just like a
+real downstream user.
 
-## Why the unusual setup
-
-Rezoom.SQL has two artifacts that interact awkwardly during dev:
-
-- The **type provider** (`Rezoom.SQL.Provider`) is loaded by `fsc` at compile
-  time, not at the consumer's runtime. To test a TP change, a project has to
-  reference a NuGet-installed version of the provider, not a project-reference
-  to its source. (Project references don't trigger the same TP loading path.)
-
-- The **TP user smoke tests** (in `src/TypeProviderUsers/`) exercise the TP
-  exactly the way a consumer would — they `PackageReference` the wrapper
-  meta-packages (e.g. `Rezoom.SQL.Provider.SQLite`) which transitively bring
-  in `Rezoom.SQL.Provider`. So testing a TP change means packing your changes,
-  then letting the TPUs restore the new package and rebuild.
-
-The local feed + version-bump dance encodes this. Run `build/pack-dev.ps1`
-after a Provider change; the TPUs (and any consumer in the repo) automatically
-restore the new version on their next build.
+If you're only working on Rezoom.SQL and don't need to make changes to Rezoom, you can use the latest published Rezoom
+from nuget.org. If you're changing both, pack Rezoom into the same `.localfeed` first using whatever script that repo
+provides.
 
 ## Versioning during dev
 
-All Rezoom.SQL packages share a single version. Two files compose it:
+All Rezoom.SQL packages share a single version. Two files define it:
 
 - `version.props` (committed): `RezoomSqlVersion = 0.13.0`, represents the upcoming or
   current release version. Bumped only at actual releases.
 - `version.local.props` (gitignored): written by `pack-dev.ps1`, contains
   `RezoomSqlVersionSuffix = dev.N`. The combined version becomes
-  `0.13.0-dev.N`. Bumped extremely frequently during development, every time we have to smoke-test the TPUs.
+  `0.13.0-dev.N`. Bumped extremely frequently during development, every time we have to "pack-dev.ps1" and smoke-test the TPUs.
 
 Every package and consumer reads these via `Directory.Build.props`. Wrapper
 csprojs and TPU / demo fsprojs reference our packages as
@@ -81,85 +63,67 @@ release version automatically.
 
 ### `build/pack-dev.ps1`
 
-Bumps the dev counter (one above the highest existing prerelease in the local
-feed), writes `version.local.props`, packs all six packages. Run after any
-change you want the TPUs or demos to see.
+Bumps the dev counter (one above the highest existing prerelease in the local feed), writes `version.local.props`, packs
+all six packages. Run after any change you want the TPUs or demos to see.
 
 ```powershell
 ./build/pack-dev.ps1
 ```
 
 ### `build/pack-release.ps1`
 
-Deletes `version.local.props` so the build has no prerelease suffix, then
-packs all six packages at the release version. Errors out if the working
-tree is dirty (override with `-Force`). After it succeeds, tag and push:
+Deletes `version.local.props` so the build has no prerelease suffix, then packs all six packages at the release version.
+Errors out if the working tree is dirty (override with `-Force`). After it succeeds, tag and push:
 
 ```powershell
 ./build/pack-release.ps1
 git tag v1.0.0
 git push origin v1.0.0
 ```
 
-Drop the `.nupkg`s into wherever your nuget.org push lives.
-
 ### `build/pack-parents.ps1`
 
-Packs the three parent libs (FParsec-Pipes, LicenseToCIL, Rezoom) from
-their sibling repos at the versions declared in each fsproj. Use this when
-you've edited a parent and want Rezoom.SQL to pick up the fresh bits.
+Packs the three parent libs (FParsec-Pipes, LicenseToCIL, Rezoom) from their sibling repos at the versions declared in
+each fsproj. Use this when you've edited a parent and want Rezoom.SQL to pick up the new dev version.
 
 ```powershell
 ./build/pack-parents.ps1                  # all three
 ./build/pack-parents.ps1 -Only Rezoom     # one at a time
 ```
 
-The parents don't participate in the centralized `version.props` mechanism
-(they change rarely; their versions are bumped manually). If you're
-publishing parent changes, bump the parent's `<Version>` first, then run
-this script.
+The parents don't participate in the centralized `version.props` mechanism (they change rarely; their versions are
+bumped manually). If you're publishing parent changes, bump the parent's `<Version>` first, then run this script.
 
 ### `build/regen-doc-nav.ps1`
 
-Rewrites the breadcrumb + prev/next nav blocks at the top and bottom of
-every doc page listed in `SUMMARY.md`. Run after editing `SUMMARY.md`
-(adding pages, reordering, renaming) to bring all nav links back into sync.
+Rewrites the breadcrumb + prev/next nav blocks at the top and bottom of every doc page listed in `SUMMARY.md`. Run after
+editing `SUMMARY.md` (adding pages, reordering, renaming) to bring all nav links back into sync.
 
 ```powershell
 ./build/regen-doc-nav.ps1
 ```
 
-Each rewritten block is fenced by HTML comment markers (`<!-- nav-top -->` /
-`<!-- nav-bottom -->`) so the script can rerun cleanly.
-
 ### `src/TypeProviderUsers/test-tp-users.ps1`
 
 Runs `dotnet test` on both TPU projects. SQLite can make its own DB file, but Postgres auto-
 skips when no server is reachable. Either set up your local Postgres like mine, with an
 `rz` user and password `testtest`, or use `REZOOM_TPU_POSTGRES` to override the
 connection string.
 
-## Why the TPUs aren't in the main sln
-
-The TPUs reference the wrapper packages via NuGet, not via project reference.
-Putting them in the same sln as `Rezoom.SQL.Provider` is confusing: opening
-the sln in VS suggests project-ref semantics, but the TPUs actually consume
-whatever's currently packed into `.localfeed`. Changing Provider source
-without running `pack-dev.ps1` would silently leave the TPUs on the old
-version.
+### `src/TypeProviderUsers/test-vs-build.ps1`
 
-They live as standalone fsprojs under `src/TypeProviderUsers/`. Open them
-individually (or via the test runner script) when you need to verify TP
-behavior end-to-end.
+Confirms the build still works in VS/MSBuild. It's very easy to write generative TP code that works in `dotnet build`
+but breaks in MSBuild.
 
 ## Edit-rebuild loop for TP work
 
 1. Edit something in `src/Rezoom.SQL.Provider/`, `Rezoom.SQL.Compiler/`, or
    `Rezoom.SQL.Mapping/`.
-2. Run `./build/pack-dev.ps1`. New version is `0.13.0-dev.<N+1>`.
-3. Run `./src/TypeProviderUsers/test-tp-users.ps1` (or `dotnet test` the specific one
+2. Make sure it passes the easy tests in Rezoom.SQL.Test and Rezoom.SQL.Provider.Test.
+3. Run `./build/pack-dev.ps1` to generate local dev packages.
+4. Run `./src/TypeProviderUsers/test-tp-users.ps1` (or `dotnet test` the specific one
    you care about). Restore picks up the new dev version automatically.
-4. Iterate.
+5. Also run `./src/TypeProviderUsers/test-vs-build.ps1` to confirm the TP works in a VS/msbuild environment too.
 
 If something doesn't update as expected, the usual suspect is a stale entry
 in `~/.nuget/packages/<pkg>/<version>/`. `pack-dev.ps1` clears those for the
@@ -173,5 +137,5 @@ the feed, you may need to clear by hand.
 3. Update `CHANGELOG.md` (when one exists) and any docs that mention versions.
 4. Commit. Working tree should be clean.
 5. Run `./build/pack-release.ps1`. Verify the resulting `.nupkg`s in the feed.
-6. Push to nuget.org via your usual mechanism.
+6. Push to nuget.org.
 7. Tag `v<version>` and push the tag.

doc/Language/DataTypes.md

@@ -49,9 +49,9 @@ an `int64` to an `int32`. When the typechecker encounters an expression such as
 `a` and `b` have the same types or one is an ancestor of the other's type.
 
 A type variable such as `@x` may be unified with types in many places. The most
-specific type always wins, so in the expression `@x >= someInt32 and @x <
-someInt16`, @x is inferred to have type `int32`, because it is lower in the type
-hierarchy than `int16`.
+specific type always wins, so in the expression
+`@x >= someInt32 and @x < someInt16`, @x is inferred to have type `int32`,
+because it is lower in the type hierarchy than `int16`.
 
 Here is the current type hierarchy. Notice that there are some types in the
 hierarchy that do not appear in the above table. These exist just as constraints
@@ -70,10 +70,10 @@ show up in the corresponding column.
 
 Most expressions (like `a * b`) are assumed to be potentially null if _either_
 of their inputs are potentially null. When an expression uses a function, the
-nullability depends on the function. For example, in TSQL, the `power(base,
-power)` function has "infectious" arguments in that if either of them is
-nullable, the output is inferred to be nullable. However, the `coalesce`
-function's output is only nullable if its last argument is nullable.
+nullability depends on the function. For example, in TSQL, the
+`power(base, power)` function has "infectious" arguments in that if either of
+them is nullable, the output is inferred to be nullable. However, the
+`coalesce` function's output is only nullable if its last argument is nullable.
 
 When a query is parameterized, RZSQL must also figure out which parameters
 should be nullable. To this end, it assumes some expressions must be nullable.
@@ -127,8 +127,8 @@ In the simplest case, as seen above, the expression is a parameter, like
 nullable.
 
 This also works for somewhat more complex expressions. For example, it could be
-a binary operation like `@count + 1`, or even a scalar sub-query, like `(select
-@name as n)`. In both these cases. the typechecker concludes that the whole
+a binary operation like `@count + 1`, or even a scalar sub-query, like
+`(select @name as n)`. In both these cases. the typechecker concludes that the whole
 subquery's result is nullable if-and-only-if the parameter in question is
 nullable, so again, it makes the parameter's type nullable to satisfy the
 constraint.

doc/Language/Quirks/PostgresQuirks.md

@@ -21,9 +21,9 @@ There is no data type in Postgres that stores a date, time, and timezone offset.
 
 You would think that `TIMESTAMP WITH TIME ZONE` would do that, but it does not.
 It stores a UTC timestamp, and annoyingly converts it to different local times
-in various situations such as during conversion to `TIMESTAMP WITHOUT TIME
-ZONE`. It is baffling to me why anybody would ever want a database to be aware
-of anybody's local time, but I'm not the database guy.
+in various situations such as during conversion to
+`TIMESTAMP WITHOUT TIME ZONE`. It is baffling to me why anybody would ever
+want a database to be aware of anybody's local time, but I'm not the database guy.
 
 When using RZSQL, both the `DateTime` and `DateTimeOffset` types are mapped to
 `TIMESTAMP WITH TIME ZONE`. With both types, querying the DB will give you a UTC

doc/Language/Quirks/TSQLQuirks.md

@@ -26,8 +26,8 @@ work for comparison with a literal `NULL` -- you can't, for example, compare two
 columns this way.
 
 When faced with a usage of `IS` or `IS NOT` that doesn't have a literal `NULL`
-as its right-hand side, RZSQL uses this idiom for `LeftSideExpr IS
-RightSideExpr`:
+as its right-hand side, RZSQL uses this idiom for
+`LeftSideExpr IS RightSideExpr`:
 
 ```sql
 EXISTS(SELECT LeftSideExpr INTERSECT SELECT RightSideExpr);
@@ -69,8 +69,8 @@ whenever a "fake boolean" is used in a boolean clause:
 SELECT * FROM SomeTable WHERE (SomeBitColumn<>0)
 ```
 
-Conversely, it adds a `CASE` expression whenever a boolean expression such as `x
-< y` is used where a scalar value is needed:
+Conversely, it adds a `CASE` expression whenever a boolean expression such as
+`x < y` is used where a scalar value is needed:
 
 ```sql
 SELECT
@@ -129,8 +129,8 @@ T-SQL models default values as constraints, and refuses to let you drop a column
 while it has constraints referencing it, even if the constraints will become
 completely pointless once the column is gone.
 
-Therefore, you must `ALTER TABLE DROP DEFAULT FOR ColumnName` before you `ALTER
-TABLE DROP COLUMN ColumnName`, if the column has a default value.
+Therefore, you must `ALTER TABLE DROP DEFAULT FOR ColumnName` before you
+`ALTER TABLE DROP COLUMN ColumnName`, if the column has a default value.
 
 You'll get informed of this at compile time.
 

doc/Language/SelectStmt.md

@@ -255,8 +255,8 @@ The four compound operators supported by RZSQL are:
 * `EXCEPT`: the result set contains all rows from the left compound term **not
   found in** the right compound term.
 
-Compound operators are all left-associative, meaning that `x except y union all
-z` groups like `(x except y) union all z`. The parentheses here are purely for
+Compound operators are all left-associative, meaning that
+`x except y union all z` groups like `(x except y) union all z`. The parentheses here are purely for
 illustration. In RZSQL, you _cannot_ use parentheses around compound exprs to
 override their associativity. If you need an associativity other than
 left-to-right, you'll need to use subqueries instead.

doc/Language/UserTypes/README.md

@@ -130,9 +130,9 @@ module MyCustomMappings =
         static member FromPrimitive(str : string) = DateOnly.ParseExact(str, "o")
 ```
 
-You can have as many classes as you want defining static custom mappings. But you can't split the mapping for a *single
-UserType* across multiple classes. `ToPrimitive : Foo -> string` has to be defined in the *same* class as `FromPrimitive
-: string -> Foo` for the mapping to be valid.
+You can have as many classes as you want defining static custom mappings. But you can't split the mapping for a
+*single UserType* across multiple classes. `ToPrimitive : Foo -> string` has to be defined in the *same* class as
+`FromPrimitive : string -> Foo` for the mapping to be valid.
 
 ## Using the mapped types
 
@@ -426,8 +426,8 @@ harder to follow for any reader of your code.
 
 You cannot map a .NET generic type as a UserType. For example, maybe every entity in your domain has a Guid PK. You
 might wish to write a single `type Id<'a> = Id of Guid` and then use `Id<User>`, `Id<Group>`, etc. instead of defining
-individual types for each one. This is not supported. You'll have to use `type UserId = UserId of Guid` and `type
-GroupId = GroupId of Guid` and so on.
+individual types for each one. This is not supported. You'll have to use
+`type UserId = UserId of Guid` and `type GroupId = GroupId of Guid` and so on.
 
 ### Changes affecting schema
 

doc/Tutorial/LoadingNestedObjects.md

@@ -60,8 +60,8 @@ users. Behind the scenes, it is getting the same old flat result set from SQL,
 but it processes it into a nested collection of objects in memory. In order to
 do this, it must have some way to de-duplicate the repeated user information. By
 default, this is done by comparing all the columns at the user level of the
-query that are selected from primary key columns -- in this case, just `u.Id as
-UserId`.
+query that are selected from primary key columns -- in this case, just
+`u.Id as UserId`.
 
 You can read more about this feature on the [Navigation
 Properties](../Language/NavigationProperties.md) page.