Rework structure to lift UserTypes doc out of Language section it didn't really belong in.

rspeele · rspeele · commit d10e2d140276 · 2026-06-08T01:30:10.000-04:00
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ nav_order: 0
 ---
 
 <!-- nav-top -->
-**Documentation:** [Tutorial](doc/Tutorial/README.md) | [Using Rezoom](doc/Rezoom/README.md) | [Configuration](doc/Configuration/README.md) | [Language](doc/Language/README.md) | [API](doc/API/README.md)
+**Documentation:** [Tutorial](doc/Tutorial/README.md) | [Using Rezoom](doc/Rezoom/README.md) | [Configuration](doc/Configuration/README.md) | [Language](doc/Language/README.md) | [UserTypes](doc/UserTypes/README.md) | [API](doc/API/README.md)
 <!-- /nav-top -->
 
 [Query playground -- try out the SQL dialect live!](https://rzsql.com/#1F854F9945C2061389778AE5DB98238E21D3A62B)
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -27,11 +27,6 @@
     * [Drop object statements](doc/Language/DropStmt.md)
     * [Navigation properties](doc/Language/NavigationProperties.md)
     * [Vendor statements](doc/Language/VendorStatements.md)
-    * [UserTypes](doc/Language/UserTypes/README.md)
-        * [Field lengths and storage type](doc/Language/UserTypes/FieldLengthsAndStorage.md)
-        * [Advanced primitive mapping](doc/Language/UserTypes/AdvancedMapping.md)
-        * [Annotation attributes reference](doc/Language/UserTypes/AttributesReference.md)
-        * [Pitfalls and limitations](doc/Language/UserTypes/Pitfalls.md)
     * [Functions](doc/Language/Functions/README.md)
         * [SQLite](doc/Language/Functions/SQLiteFunctions.md)
         * [TSQL](doc/Language/Functions/TSQLFunctions.md)
@@ -41,7 +36,12 @@
         * [TSQL](doc/Language/Quirks/TSQLQuirks.md)
         * [Postgres](doc/Language/Quirks/PostgresQuirks.md)
     * [Dynamic SQL](doc/Language/DynamicSQL.md)
-    * [What's missing?](doc/Language/MissingFeatures.md)
+    * [Language Omissions](doc/Language/MissingFeatures.md)
+* [UserTypes](doc/UserTypes/README.md)
+    * [Field lengths and storage type](doc/UserTypes/FieldLengthsAndStorage.md)
+    * [Advanced primitive mapping](doc/UserTypes/AdvancedMapping.md)
+    * [Annotation attributes reference](doc/UserTypes/AttributesReference.md)
+    * [Pitfalls and limitations](doc/UserTypes/Pitfalls.md)
 * [API](doc/API/README.md)
     * [Rezoom.SQL](doc/API/RezoomSQL.md)
     * [Rezoom.SQL.Synchronous](doc/API/RezoomSQLSynchronous.md)
diff --git a/doc/API/README.md b/doc/API/README.md
@@ -1,13 +1,13 @@
 ---
 title: API
-nav_order: 6
+nav_order: 7
 has_children: true
 ---
 
 <!-- nav-top -->
 [Home](../../README.md) &gt; API
 
-[&larr; What's missing?](../Language/MissingFeatures.md) | [Rezoom.SQL &rarr;](RezoomSQL.md)
+[&larr; Pitfalls and limitations](../UserTypes/Pitfalls.md) | [Rezoom.SQL &rarr;](RezoomSQL.md)
 <!-- /nav-top -->
 
 # API
@@ -44,6 +44,6 @@ outside the lines and minor version releases may break the API.
 
 ---
 <!-- nav-bottom -->
-[&larr; What's missing?](../Language/MissingFeatures.md) | [Rezoom.SQL &rarr;](RezoomSQL.md)
+[&larr; Pitfalls and limitations](../UserTypes/Pitfalls.md) | [Rezoom.SQL &rarr;](RezoomSQL.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/Configuration/Json.md b/doc/Configuration/Json.md
@@ -127,7 +127,7 @@ Reference the assembly full name in rzsql.json like so:
 
 Your F# project using the type provider must also reference the MyProduct.MyCustomTypesAssembly project.
 
-Read [the full UserTypes feature documentation here](../Language/UserTypes/README.md).
+Read [the full UserTypes feature documentation here](../UserTypes/README.md).
 
 You can reference multiple assemblies in this list. For example, you could have your primitive mappings in one assembly
 and your row interfaces in another.
diff --git a/doc/Language/DynamicSQL.md b/doc/Language/DynamicSQL.md
@@ -1,13 +1,13 @@
 ---
 title: Dynamic SQL
 parent: Language
-nav_order: 19
+nav_order: 18
 ---
 
 <!-- nav-top -->
 [Home](../../README.md) &gt; [Language](README.md) &gt; Dynamic SQL
 
-[&larr; Postgres](Quirks/PostgresQuirks.md) | [What's missing? &rarr;](MissingFeatures.md)
+[&larr; Postgres](Quirks/PostgresQuirks.md) | [Language Omissions &rarr;](MissingFeatures.md)
 <!-- /nav-top -->
 
 # Dynamic SQL
@@ -103,6 +103,6 @@ let exampleCommand (nameSearch : string) =
 
 ---
 <!-- nav-bottom -->
-[&larr; Postgres](Quirks/PostgresQuirks.md) | [What's missing? &rarr;](MissingFeatures.md)
+[&larr; Postgres](Quirks/PostgresQuirks.md) | [Language Omissions &rarr;](MissingFeatures.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/Language/Functions/README.md b/doc/Language/Functions/README.md
@@ -1,14 +1,14 @@
 ---
 title: Functions
 parent: Language
-nav_order: 17
+nav_order: 16
 has_children: true
 ---
 
 <!-- nav-top -->
 [Home](../../../README.md) &gt; [Language](../README.md) &gt; Functions
 
-[&larr; Pitfalls and limitations](../UserTypes/Pitfalls.md) | [SQLite &rarr;](SQLiteFunctions.md)
+[&larr; Vendor statements](../VendorStatements.md) | [SQLite &rarr;](SQLiteFunctions.md)
 <!-- /nav-top -->
 
 # Functions
@@ -119,6 +119,6 @@ This way, only `@b` will be nullable.
 
 ---
 <!-- nav-bottom -->
-[&larr; Pitfalls and limitations](../UserTypes/Pitfalls.md) | [SQLite &rarr;](SQLiteFunctions.md)
+[&larr; Vendor statements](../VendorStatements.md) | [SQLite &rarr;](SQLiteFunctions.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/Language/MissingFeatures.md b/doc/Language/MissingFeatures.md
@@ -1,16 +1,16 @@
 ---
-title: What's missing?
+title: Language Omissions
 parent: Language
-nav_order: 20
+nav_order: 19
 ---
 
 <!-- nav-top -->
-[Home](../../README.md) &gt; [Language](README.md) &gt; What's missing?
+[Home](../../README.md) &gt; [Language](README.md) &gt; Language Omissions
 
-[&larr; Dynamic SQL](DynamicSQL.md) | [API &rarr;](../API/README.md)
+[&larr; Dynamic SQL](DynamicSQL.md) | [UserTypes &rarr;](../UserTypes/README.md)
 <!-- /nav-top -->
 
-# What's missing?
+# Language Omissions
 
 If you are already familiar with a SQL dialect, here are some features you may
 miss that are not currently supported by RZSQL.
@@ -25,6 +25,7 @@ goals and would make sense to add eventually. Pull requests would of course be
 appreciated!
 
 * Support for mixing dynamic SQL into static queries, especially `ORDER BY` clause
+* Tools to generate an RZSQL migration file from an existing DB
 * Window functions
 * Table-valued functions
 * User-defined functions
@@ -53,6 +54,6 @@ though!
 
 ---
 <!-- nav-bottom -->
-[&larr; Dynamic SQL](DynamicSQL.md) | [API &rarr;](../API/README.md)
+[&larr; Dynamic SQL](DynamicSQL.md) | [UserTypes &rarr;](../UserTypes/README.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/Language/Quirks/README.md b/doc/Language/Quirks/README.md
@@ -1,7 +1,7 @@
 ---
 title: Quirks
 parent: Language
-nav_order: 18
+nav_order: 17
 has_children: true
 ---
 
diff --git a/doc/Language/VendorStatements.md b/doc/Language/VendorStatements.md
@@ -7,7 +7,7 @@ nav_order: 15
 <!-- nav-top -->
 [Home](../../README.md) &gt; [Language](README.md) &gt; Vendor statements
 
-[&larr; Navigation properties](NavigationProperties.md) | [UserTypes &rarr;](UserTypes/README.md)
+[&larr; Navigation properties](NavigationProperties.md) | [Functions &rarr;](Functions/README.md)
 <!-- /nav-top -->
 
 # Vendor Statements
@@ -144,6 +144,6 @@ vendor tsql <#
 
 ---
 <!-- nav-bottom -->
-[&larr; Navigation properties](NavigationProperties.md) | [UserTypes &rarr;](UserTypes/README.md)
+[&larr; Navigation properties](NavigationProperties.md) | [Functions &rarr;](Functions/README.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/UserTypes/AdvancedMapping.md b/doc/UserTypes/AdvancedMapping.md
@@ -1,12 +1,11 @@
 ---
 title: Advanced primitive mapping
 parent: UserTypes
-grand_parent: Language
 nav_order: 2
 ---
 
 <!-- nav-top -->
-[Home](../../../README.md) &gt; [Language](../README.md) &gt; [UserTypes](README.md) &gt; Advanced primitive mapping
+[Home](../../README.md) &gt; [UserTypes](README.md) &gt; Advanced primitive mapping
 
 [&larr; Field lengths and storage type](FieldLengthsAndStorage.md) | [Annotation attributes reference &rarr;](AttributesReference.md)
 <!-- /nav-top -->
@@ -61,7 +60,7 @@ these types can be the right call.
 
 ## Mapping to vendor-specific database column types
 
-In addition to the aforementioned [built-in primitive](../DataTypes.md) datatypes, your `ToPrimitive` and
+In addition to the aforementioned [built-in primitive](../Language/DataTypes.md) datatypes, your `ToPrimitive` and
 `FromPrimitive` methods can map a UserType to `System.Object`.
 
 This allows you to store and retrieve *anything* your underlying ADO.NET provider can handle.
@@ -122,7 +121,7 @@ being the integer value of NpgsqlDbType.Point.
 The above example helped you store a `point` and retrieve it, but you still can't do much with it in your database
 queries. RZSQL doesn't know what operations `point` supports, and doesn't have type signatures for Postgres's geometric
 functions, because they don't fit into its default backend-agnostic type hierarchy. For doing more than just CRUD
-storage and retrieval, you'll want to get familiar with [VENDOR statements](../VendorStatements.md).
+storage and retrieval, you'll want to get familiar with [VENDOR statements](../Language/VendorStatements.md).
 
 ---
 <!-- nav-bottom -->
diff --git a/doc/UserTypes/AttributesReference.md b/doc/UserTypes/AttributesReference.md
@@ -1,12 +1,11 @@
 ---
 title: Annotation attributes reference
 parent: UserTypes
-grand_parent: Language
 nav_order: 3
 ---
 
 <!-- nav-top -->
-[Home](../../../README.md) &gt; [Language](../README.md) &gt; [UserTypes](README.md) &gt; Annotation attributes reference
+[Home](../../README.md) &gt; [UserTypes](README.md) &gt; Annotation attributes reference
 
 [&larr; Advanced primitive mapping](AdvancedMapping.md) | [Pitfalls and limitations &rarr;](Pitfalls.md)
 <!-- /nav-top -->
diff --git a/doc/UserTypes/FieldLengthsAndStorage.md b/doc/UserTypes/FieldLengthsAndStorage.md
@@ -1,12 +1,11 @@
 ---
 title: Field lengths and storage type
 parent: UserTypes
-grand_parent: Language
 nav_order: 1
 ---
 
 <!-- nav-top -->
-[Home](../../../README.md) &gt; [Language](../README.md) &gt; [UserTypes](README.md) &gt; Field lengths and storage type
+[Home](../../README.md) &gt; [UserTypes](README.md) &gt; Field lengths and storage type
 
 [&larr; UserTypes](README.md) | [Advanced primitive mapping &rarr;](AdvancedMapping.md)
 <!-- /nav-top -->
diff --git a/doc/UserTypes/Pitfalls.md b/doc/UserTypes/Pitfalls.md
@@ -1,14 +1,13 @@
 ---
 title: Pitfalls and limitations
 parent: UserTypes
-grand_parent: Language
 nav_order: 4
 ---
 
 <!-- nav-top -->
-[Home](../../../README.md) &gt; [Language](../README.md) &gt; [UserTypes](README.md) &gt; Pitfalls and limitations
+[Home](../../README.md) &gt; [UserTypes](README.md) &gt; Pitfalls and limitations
 
-[&larr; Annotation attributes reference](AttributesReference.md) | [Functions &rarr;](../Functions/README.md)
+[&larr; Annotation attributes reference](AttributesReference.md) | [API &rarr;](../API/README.md)
 <!-- /nav-top -->
 
 # Pitfalls and limitations
@@ -48,7 +47,7 @@ Now that you've changed the `TimeOnly` mapping, RZSQL thinks that old migration
 existence of the `nvarchar` column has been memory-holed: we have always been at war with Eastasia. Your queries will
 fail at runtime because RZSQL's idea of your database model no longer matches reality.
 
-The solution is to write a new migration and use a [VENDOR statement](../VendorStatements.md) to port data over from the old
+The solution is to write a new migration and use a [VENDOR statement](../Language/VendorStatements.md) to port data over from the old
 format to the new. The vendor statement will allow you to bypass RZSQL's outdated conception of the data types and work
 on the real data in the table. Something like:
 
@@ -71,6 +70,6 @@ The key thing to remember here is it is up to you to be disciplined about changi
 
 ---
 <!-- nav-bottom -->
-[&larr; Annotation attributes reference](AttributesReference.md) | [Functions &rarr;](../Functions/README.md)
+[&larr; Annotation attributes reference](AttributesReference.md) | [API &rarr;](../API/README.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/UserTypes/README.md b/doc/UserTypes/README.md
@@ -1,14 +1,13 @@
 ---
 title: UserTypes
-parent: Language
-nav_order: 16
+nav_order: 6
 has_children: true
 ---
 
 <!-- nav-top -->
-[Home](../../../README.md) &gt; [Language](../README.md) &gt; UserTypes
+[Home](../../README.md) &gt; UserTypes
 
-[&larr; Vendor statements](../VendorStatements.md) | [Field lengths and storage type &rarr;](FieldLengthsAndStorage.md)
+[&larr; Language Omissions](../Language/MissingFeatures.md) | [Field lengths and storage type &rarr;](FieldLengthsAndStorage.md)
 <!-- /nav-top -->
 
 # UserTypes
@@ -33,7 +32,7 @@ Your UserTypes MUST be in a separate assembly from your SQL queries, and must bu
 The type provider cannot "see" types defined in the same assembly it's trying to compile. They don't exist yet!
 
 The fsproj where you're using Rezoom.SQL.Provider must have a project reference to your UserType project(s). It must
-**also** name those projects in [rzsql.json's](../../Configuration/Json.md) `"usertypes"` list. This tells the type
+**also** name those projects in [rzsql.json's](../Configuration/Json.md) `"usertypes"` list. This tells the type
 provider to search the listed assemblies at design-time to find your custom types.
 
 Referencing Rezoom.SQL.Annotations is optional. This is a lightweight package that only defines attributes.
@@ -69,7 +68,7 @@ With UserTypes you can solve this. A user-mapped primitive type can take either
 ### Single-case union
 
 This is the simplest case. Any F# union type with a single case that wraps an underlying [built-in
-primitive](../DataTypes.md) will automatically be detected as a valid UserType without needing further annotations or
+primitive](../Language/DataTypes.md) will automatically be detected as a valid UserType without needing further annotations or
 methods.
 
 ```fsharp
@@ -137,7 +136,7 @@ You can have as many classes as you want defining static custom mappings. But yo
 
 ## Using the mapped types
 
-Once you've got your UserTypes assembly plugged in via [rzsql.json](../../Configuration/Json.md), you can use your
+Once you've got your UserTypes assembly plugged in via [rzsql.json](../Configuration/Json.md), you can use your
 domain types in your database model. Instead of writing `create table Users(Id guid primary key)`, write `create table Users(Id UserId primary key)`.
 
 **Note that while built-in types in RZSQL are case-insensitive, when you reference a UserType you *must* match its .NET type name exactly, case-sensitively!**
@@ -213,6 +212,6 @@ select<IUserRow, ISoftDelete, IHasThumbnail, IHaveALotOfInterfaces> * from Users
 
 ---
 <!-- nav-bottom -->
-[&larr; Vendor statements](../VendorStatements.md) | [Field lengths and storage type &rarr;](FieldLengthsAndStorage.md)
+[&larr; Language Omissions](../Language/MissingFeatures.md) | [Field lengths and storage type &rarr;](FieldLengthsAndStorage.md)
 <!-- /nav-bottom -->
 
diff --git a/doc/UserTypes/SolutionLayout.gv b/doc/UserTypes/SolutionLayout.gv
diff --git a/doc/UserTypes/SolutionLayout.gv.svg b/doc/UserTypes/SolutionLayout.gv.svg
