docs: move migration docs into book

README.md

@@ -20,7 +20,7 @@ Please see [here](UKRAINE.md) for an important message for the people of Russia.
 > for the latest stable release.
 >
 > As a major release, there are some breaking API changes,
-> but a [migration guide](docs/migrating/nng1.md) is
+> but a [migration guide](docs/ref/migrate/nng1.md) is
 > available to help with migrating from NNG 1.x.
 
 > [!NOTE]
@@ -186,7 +186,7 @@ These are located in the `demo` directory.
 ## Legacy Compatibility
 
 Migration from `libnanomsg` APIs is fairly straight-forward for most applications.
-A [migration guide](docs/migrating/nanomsg.md) is available to assist.
+A [migration guide](docs/ref/migrate/nanomsg.md) is available to assist.
 
 ## Commercial Support
 

docs/ref/SUMMARY.md

@@ -55,4 +55,9 @@
   - [BSD Socket (Experimental)](./tran/socket.md)
   - [UDP Transport (Experimental)](./tran/udp.md)
 
+- [Migration Guides](./migrate/index.md)
+
+  - [Migrating from NNG 1.x](./migrate/nng1.md)
+  - [Migrating from libnanomsg](./migrate/nanomsg.md)
+
 [Index](./indexing.md)

docs/ref/migrate/index.md

@@ -0,0 +1,7 @@
+# Migration Guides
+
+This section provides some guides to aid in migrating software from
+earlier versions _NNG_ or _libnanomsg_.
+
+- [Migrating from NNG 1.x](./migrate/nng1.md)
+- [Migrating from libnanomsg](./migrate/nanomsg.md)

docs/migrating/nng1.md → docs/ref/migrate/nng1.md

@@ -5,8 +5,8 @@ This guide should help in migrating applications to use NNG 2.0.
 
 ## Nanomsg Compatibility
 
-Applications using the legacy `libnanomsg` API will have to be updated to native NNG interfaces.
-See the [Migration Guide for libnanomsg](nanomsg.md) for details.
+Applications using the legacy `libnanomsg` API will have to be updated to native _NNG_ interfaces.
+See the [Migrating From libnanomsg](nanomsg.md) chapter for details.
 
 ## Transport Specific Functions