Organization and content

28 files changed, 294 insertions, 74 deletions

diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index c99877c1..4ae2c79b 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -20,30 +20,29 @@
 
   - [Asynchronous I/O](./api/aio/index.md)
 
-    - [nng_aio](api/nng_aio.md)
-    - [nng_aio_abort](api/nng_aio_abort.md)
-    - [nng_aio_alloc](api/nng_aio_alloc.md)
-    - [nng_aio_busy](api/nng_aio_busy.md)
-    - [nng_aio_cancel](api/nng_aio_cancel.md)
-    - [nng_aio_count](api/nng_aio_count.md)
-    - [nng_aio_free](api/nng_aio_free.md)
-    - [nng_aio_get_msg](api/nng_aio_get_msg.md)
-    - [nng_aio_get_output](api/nng_aio_get_output.md)
-    - [nng_aio_result](api/nng_aio_result.md)
-    - [nng_aio_set_input](api/nng_aio_set_input.md)
-    - [nng_aio_set_iov](api/nng_aio_set_iov.md)
-    - [nng_aio_set_msg](api/nng_aio_set_msg.md)
-    - [nng_aio_set_timeout](api/nng_aio_set_timeout.md)
-    - [nng_aio_stop](api/nng_aio_stop.md)
-    - [nng_aio_wait](api/nng_aio_wait.md)
-
-  - [Asynchronous I/O for Providers](api/aio_provider.md)
-
-    - [nng_aio_begin](api/nng_aio_begin.md)
-    - [nng_aio_defer](api/nng_aio_defer.md)
-    - [nng_aio_finish](api/nng_aio_finish.md)
-    - [nng_aio_get_input](api/nng_aio_get_input.md)
-    - [nng_aio_set_output](api/nng_aio_set_output.md)
+    - [nng_aio_abort](api/aio/nng_aio_abort.md)
+    - [nng_aio_alloc](api/aio/nng_aio_alloc.md)
+    - [nng_aio_busy](api/aio/nng_aio_busy.md)
+    - [nng_aio_cancel](api/aio/nng_aio_cancel.md)
+    - [nng_aio_count](api/aio/nng_aio_count.md)
+    - [nng_aio_free](api/aio/nng_aio_free.md)
+    - [nng_aio_get_msg](api/aio/nng_aio_get_msg.md)
+    - [nng_aio_get_output](api/aio/nng_aio_get_output.md)
+    - [nng_aio_result](api/aio/nng_aio_result.md)
+    - [nng_aio_set_input](api/aio/nng_aio_set_input.md)
+    - [nng_aio_set_iov](api/aio/nng_aio_set_iov.md)
+    - [nng_aio_set_msg](api/aio/nng_aio_set_msg.md)
+    - [nng_aio_set_timeout](api/aio/nng_aio_set_timeout.md)
+    - [nng_aio_stop](api/aio/nng_aio_stop.md)
+    - [nng_aio_wait](api/aio/nng_aio_wait.md)
+
+  - [Asynchronous I/O for Providers](api/aio_provider/index.md)
+
+    - [nng_aio_begin](api/aio_provider/nng_aio_begin.md)
+    - [nng_aio_defer](api/aio_provider/nng_aio_defer.md)
+    - [nng_aio_finish](api/aio_provider/nng_aio_finish.md)
+    - [nng_aio_get_input](api/aio_provider/nng_aio_get_input.md)
+    - [nng_aio_set_output](api/aio_provider/nng_aio_set_output.md)
 
   - [General Purpose Functions](api/general.md)
 
diff --git a/docs/reference/src/api/aio/index.md b/docs/reference/src/api/aio/index.md
new file mode 100644
index 00000000..4c49ff78
--- /dev/null
+++ b/docs/reference/src/api/aio/index.md
@@ -0,0 +1,74 @@
+# Interfaces for Aysnchronous I/O
+
+_NNG_ provides rich support for {{i:asynchronous I/O}}.
+This allows applications to achieve high levels of concurrency with a
+minimum of fuss, optimized for the platform.
+
+Asynchronous I/O is performed without blocking calling application
+threads, so they may continue to perform other work.
+
+## AIO Handles
+
+Applications create an `nng_aio` object with a function to call when
+the operation is done (along with a pointer to application private data),
+then submit the operation.
+
+These `nng_aio` objects are created using the [`nng_aio_alloc()`](nng_aio_alloc.md),
+and destroyed using [`nng_aio_free()`](nng_aio_free.md).
+
+The `nng_aio` object itself is declared like this:
+
+```c
+#include <nng/nng.h>
+
+typedef struct nng_aio nng_aio;
+```
+
+Every asynchronous operation uses its own instance an `nng_aio`, and each
+`nng_aio` can only be used with a single operation at a time.
+
+> [!IMPORTANT]
+> Attempting to submit an operation using an `nng_aio` that is already
+> in use for another operation will crash the application.
+> However, it is possible to submit another operation on the `nng_aio` from
+> the callback associated with the same `nng_aio`.
+
+When the operation is complete, whether successfully
+or otherwise, the callback function is executed.
+The callback will be executed exactly once.
+
+## Cancellation
+
+The asynchronous I/O framework also supports cancellation of
+operations that are already in progress
+(see [`nng_aio_cancel()`](nng_aio_cancel.md)), as well setting a maximum
+timeout for them to complete within
+(see [`nng_aio_set_timeout()`](nng_aio_set_timeout.md)).
+
+## Waiting for Completion
+
+It is also possible to initiate an asynchronous operation, and wait for it to
+complete [`nng_aio_wait()`](nng_aio_wait.md).
+
+> [!IMPORTANT]
+> Applications must never call [`nng_aio_wait()`](nng_aio_wait.md) or
+> [`nng_aio_stop()`](nng_aio_stop.md) from a callback registered to
+> an `nng_aio` object. Doing so can lead to a deadlock.
+
+## See Also
+
+[nng_aio_abort()](nng_aio_abort.md),
+[nng_aio_alloc()](nng_aio_alloc.md),
+[nng_aio_cancel()](nng_aio_cancel.md),
+[nng_aio_count()](nng_aio_count.md),
+[nng_aio_free()](nng_aio_free.md),
+[nng_aio_get_input()](nng_aio_get_input.md),
+[nng_aio_get_msg()](nng_aio_get_msg.md),
+[nng_aio_get_output()](nng_aio_get_output.md),
+[nng_aio_result()](nng_aio_result.md),
+[nng_aio_set_input()](nng_aio_set_input.md),
+[nng_aio_set_iov()](nng_aio_set_iov.md),
+[nng_aio_set_msg()](nng_aio_set_msg.md),
+[nng_aio_set_timeout()](nng_aio_set_timeout.md),
+[nng_aio_stop()](nng_aio_stop.md),
+[nng_aio_wait()](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_abort.md b/docs/reference/src/api/aio/nng_aio_abort.md
index 4f4b8773..09e0fd2e 100644
--- a/docs/reference/src/api/nng_aio_abort.md
+++ b/docs/reference/src/api/aio/nng_aio_abort.md
@@ -32,5 +32,4 @@ has no effect.
 
 [nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_cancel()](nng_aio_cancel.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_result()](nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_alloc.md b/docs/reference/src/api/aio/nng_aio_alloc.md
index 4acb45aa..1f3f6be8 100644
--- a/docs/reference/src/api/nng_aio_alloc.md
+++ b/docs/reference/src/api/aio/nng_aio_alloc.md
@@ -32,7 +32,7 @@ It will be called with the argument _arg_.
 > thread can be used, along with a [condition variable](nng_cv_alloc.md)
 > which can be signaled by the callback.
 
-Asynchronous I/O operations all take an [`nng_aio`](nng_aio.md)
+Asynchronous I/O operations all take an [`nng_aio`](index.md)
 handle such as allocated by this function.
 Such operations are usually started by a function that returns immediately.
 The operation is then run asynchronously, and completes sometime later.
@@ -71,6 +71,4 @@ This function returns 0 on success, and non-zero otherwise.
 [nng_aio_set_msg()](nng_aio_set_msg.md),
 [nng_aio_set_timeout()](nng_aio_set_timeout.md),
 [nng_aio_stop()](nng_aio_stop.md),
-[nng_aio_wait()](nng_aio_wait.md),
-[nng_strerror()](nng_strerror.md),
-[nng_aio](nng_aio.md)
+[nng_aio_wait()](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_busy.md b/docs/reference/src/api/aio/nng_aio_busy.md
index f5a1003b..2a794a83 100644
--- a/docs/reference/src/api/nng_aio_busy.md
+++ b/docs/reference/src/api/aio/nng_aio_busy.md
@@ -38,5 +38,4 @@ True if the _aio_ is busy, false otherwise.
 
 [nng_aio_abort()](nng_aio_abort.md),
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_wait(3)](nng_aio_wait.md),
-[nng_aio](nng_aio.md)
+[nng_aio_wait(3)](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_cancel.md b/docs/reference/src/api/aio/nng_aio_cancel.md
index 1bb8869e..63cad987 100644
--- a/docs/reference/src/api/nng_aio_cancel.md
+++ b/docs/reference/src/api/aio/nng_aio_cancel.md
@@ -34,5 +34,4 @@ This function is the same as calling
 
 [nng_aio_abort()](nng_aio_abort.md),
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_result()](nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_count.md b/docs/reference/src/api/aio/nng_aio_count.md
index 2ce22786..a4da3c64 100644
--- a/docs/reference/src/api/nng_aio_count.md
+++ b/docs/reference/src/api/aio/nng_aio_count.md
@@ -38,9 +38,7 @@ The number of bytes transferred by the operation.
 
 ## SEE ALSO
 
-[.text-left]
 [nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_result()](nng_aio_result.md),
 [nng_aio_set_iov()](nng_aio_set_iov.md),
-[nng_aio_wait()](nng_aio_wait.md),
-[nng_aio](nng_aio)
+[nng_aio_wait()](nng_aio_wait.md)
diff --git a/docs/reference/src/api/nng_aio_free.md b/docs/reference/src/api/aio/nng_aio_free.md
index c558535d..c558535d 100644
--- a/docs/reference/src/api/nng_aio_free.md
+++ b/docs/reference/src/api/aio/nng_aio_free.md
diff --git a/docs/reference/src/api/nng_aio_get_msg.md b/docs/reference/src/api/aio/nng_aio_get_msg.md
index 70e18be9..55f712db 100644
--- a/docs/reference/src/api/nng_aio_get_msg.md
+++ b/docs/reference/src/api/aio/nng_aio_get_msg.md
@@ -27,5 +27,4 @@ or that was previously stored with
 
 [nng_aio_set_msg()](nng_aio_set_msg.md),
 [nng_recv_aio()](nng_recv_aio.md),
-[nng_aio](nng_aio.md),
 [nng_msg](nng_msg.md)
diff --git a/docs/reference/src/api/nng_aio_get_output.md b/docs/reference/src/api/aio/nng_aio_get_output.md
index 8f0a10a4..d25c1c20 100644
--- a/docs/reference/src/api/nng_aio_get_output.md
+++ b/docs/reference/src/api/aio/nng_aio_get_output.md
@@ -36,6 +36,5 @@ The _index_&zwj;th output from the operation, or `NULL`.
 ## SEE ALSO
 
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_set_output()](nng_aio_set_output.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md),
+[nng_aio_set_output()](../aio_provider/nng_aio_set_output.md),
+[nng_aio_result()](nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_result.md b/docs/reference/src/api/aio/nng_aio_result.md
index fe6688fd..fe6688fd 100644
--- a/docs/reference/src/api/nng_aio_result.md
+++ b/docs/reference/src/api/aio/nng_aio_result.md
diff --git a/docs/reference/src/api/nng_aio_set_input.md b/docs/reference/src/api/aio/nng_aio_set_input.md
index 739489ad..1b3e0883 100644
--- a/docs/reference/src/api/nng_aio_set_input.md
+++ b/docs/reference/src/api/aio/nng_aio_set_input.md
@@ -39,5 +39,4 @@ the [`nng_aio_get_input()`](nng_aio_get_input.md) function.
 ## SEE ALSO
 
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_get_input()](nng_aio_get_input.md),
-[nng_aio](nng_aio.md)
+[nng_aio_get_input()](../aio_provider/nng_aio_get_input.md)
diff --git a/docs/reference/src/api/nng_aio_set_iov.md b/docs/reference/src/api/aio/nng_aio_set_iov.md
index 4093b5e3..0c33153d 100644
--- a/docs/reference/src/api/nng_aio_set_iov.md
+++ b/docs/reference/src/api/aio/nng_aio_set_iov.md
@@ -38,8 +38,3 @@ This function returns 0 on success, and non-zero otherwise.
 ## ERRORS
 
 - `NNG_EINVAL`: Value of specified _niov_ is too large.
-
-## SEE ALSO
-
-[nng_aio](nng_aio),
-[nng_iov](nng_iov)
diff --git a/docs/reference/src/api/nng_aio_set_msg.md b/docs/reference/src/api/aio/nng_aio_set_msg.md
index eb0bd4ed..24ba9f60 100644
--- a/docs/reference/src/api/nng_aio_set_msg.md
+++ b/docs/reference/src/api/aio/nng_aio_set_msg.md
@@ -25,5 +25,4 @@ for an asynchronous send operation (see
 
 [nng_aio_get_msg()](nng_aio_get_msg.md),
 [nng_send_aio()](nng_send_aio.md),
-[nng_aio](nng_aio.md),
 [nng_msg](nng_msg.md)
diff --git a/docs/reference/src/api/nng_aio_set_timeout.md b/docs/reference/src/api/aio/nng_aio_set_timeout.md
index e8643570..b0bab9ab 100644
--- a/docs/reference/src/api/nng_aio_set_timeout.md
+++ b/docs/reference/src/api/aio/nng_aio_set_timeout.md
@@ -50,5 +50,4 @@ or absolute timeout.
 
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio),
 [nng_duration](nng_duration)
diff --git a/docs/reference/src/api/nng_aio_stop.md b/docs/reference/src/api/aio/nng_aio_stop.md
index 4cfe41b6..8ac32a76 100644
--- a/docs/reference/src/api/nng_aio_stop.md
+++ b/docs/reference/src/api/aio/nng_aio_stop.md
@@ -36,5 +36,4 @@ pending for it.
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_free()](nng_aio_free.md),
 [nng_aio_begin()](nng_aio_begin.md),
-[nng_aio_wait()](nng_aio-wait.md),
-[nng_aio](nng_aio.md),
+[nng_aio_wait()](nng_aio-wait.md)
diff --git a/docs/reference/src/api/nng_aio_wait.md b/docs/reference/src/api/aio/nng_aio_wait.md
index 2cddcb29..52f5671e 100644
--- a/docs/reference/src/api/nng_aio_wait.md
+++ b/docs/reference/src/api/aio/nng_aio_wait.md
@@ -30,5 +30,4 @@ function will not be called until the callback has completed.
 ## SEE ALSO
 
 [nng_aio_abort()](nng_aio_abort.md),
-[nng_aio_busy()](nng_aio_busy.md),
-[nng_aio](nng_aio.md)
+[nng_aio_busy()](nng_aio_busy.md)
diff --git a/docs/reference/src/api/aio_provider/index.md b/docs/reference/src/api/aio_provider/index.md
new file mode 100644
index 00000000..75a47358
--- /dev/null
+++ b/docs/reference/src/api/aio_provider/index.md
@@ -0,0 +1,21 @@
+# Asynchronous I/O for Providers
+
+I/O providers perform the operations that are linked to
+an [`nng_aio`](../aio/index.md) object, on behalf of applications
+that submit requests for the same operations.
+
+Most applications will not use the functions listed here.
+Applications that implement their own HTTP handler functions, or
+custom transport providers, might make use of these functions.
+
+In addition to these functions, I/O providers may utilize the
+other consumer functions for [Aysnchronous I/O](../aio/index.md).
+
+## See Also
+
+[nng_aio_begin()](nng_aio_begin.md),
+[nng_aio_defer()](nng_aio_defer.md),
+[nng_aio_finish()](nng_aio_finish.md),
+[nng_aio_get_input()](nng_aio_get_input.md),
+[nng_aio_set_output()](nng_aio_set_output.md),
+[Asynchronous I/O](../aio/index.md)
diff --git a/docs/reference/src/api/nng_aio_begin.md b/docs/reference/src/api/aio_provider/nng_aio_begin.md
index da817091..8e342b26 100644
--- a/docs/reference/src/api/nng_aio_begin.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_begin.md
@@ -39,9 +39,6 @@ exactly once, when the operation is complete or canceled.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_cancel()](nng_aio_cancel.md),
+[nng_aio_cancel()](../aio/nng_aio_cancel.md),
 [nng_aio_defer()](nng_aio_defer.md),
-[nng_aio_finish()](nng_aio_finish.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_finish()](nng_aio_finish.md)
diff --git a/docs/reference/src/api/nng_aio_defer.md b/docs/reference/src/api/aio_provider/nng_aio_defer.md
index 6b634f42..93d84769 100644
--- a/docs/reference/src/api/nng_aio_defer.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_defer.md
@@ -53,7 +53,6 @@ error code specified by _err_.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_cancel()](nng_aio_cancel.md),
-[nng_aio_finish()](nng_aio_finish.md),
-[nng_aio](nng_aio.md)
+[nng_aio_alloc()](../aio/nng_aio_alloc.md),
+[nng_aio_cancel()](../aio/nng_aio_cancel.md),
+[nng_aio_finish()](nng_aio_finish.md)
diff --git a/docs/reference/src/api/nng_aio_finish.md b/docs/reference/src/api/aio_provider/nng_aio_finish.md
index 48a52151..61b1ca42 100644
--- a/docs/reference/src/api/nng_aio_finish.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_finish.md
@@ -16,7 +16,7 @@ void nng_aio_finish(nng_aio *aio, int err);
 
 The `nng_aio_finish()` function marks operation associated with _aio_ as
 complete, with the status _err_.
-This will be the result returned by [`nng_aio_result()`](nng_aio_result.md).
+This will be the result returned by [`nng_aio_result()`](../aio/nng_aio_result.md).
 
 This function causes the callback associated with the _aio_ to called.
 
@@ -33,9 +33,7 @@ This function causes the callback associated with the _aio_ to called.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_begin()](nng_aio_begin.md),
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_defer()](nng_aio_defer.md),
-[nng_aio_result()](nng_aio_result.md),
-[nng_aio](nng_aio.md)
+[nng_aio_result()](../aio/nng_aio_result.md)
diff --git a/docs/reference/src/api/nng_aio_get_input.md b/docs/reference/src/api/aio_provider/nng_aio_get_input.md
index 192c82d3..28ecb797 100644
--- a/docs/reference/src/api/nng_aio_get_input.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_get_input.md
@@ -29,7 +29,6 @@ Value previously set, or `NULL`.
 
 ## SEE ALSO
 
-[nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_get_output()](nng_aio_get_output.md),
-[nng_aio_set_input()](nng_aio_set_input.md),
-[nng_aio](nng_aio.md)
+[nng_aio_alloc()](../aio/nng_aio_alloc.md),
+[nng_aio_get_output()](../aio/nng_aio_get_output.md),
+[nng_aio_set_input()](../aio/nng_aio_set_input.md)
diff --git a/docs/reference/src/api/nng_aio_set_output.md b/docs/reference/src/api/aio_provider/nng_aio_set_output.md
index c3c86440..6a79e429 100644
--- a/docs/reference/src/api/nng_aio_set_output.md
+++ b/docs/reference/src/api/aio_provider/nng_aio_set_output.md
@@ -33,5 +33,4 @@ the [`nng_aio_get_output()`](nng_aio_get_output.md) function.
 
 ## SEE ALSO
 
-[nng_aio_get_output(3)](nng_aio_get_output.md),
-[nng_aio](nng_aio.md)
+[nng_aio_get_output(3)](../aio/nng_aio_get_output.md)
diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md
index 0d1089e3..1541b541 100644
--- a/docs/reference/src/api/index.md
+++ b/docs/reference/src/api/index.md
@@ -1,8 +1,23 @@
 # API Reference
 
-This section documents the functions and data structures that make up
+This chapter documents the functions and data structures that make up
 the _NNG_ programming interface.
 
 > [!NOTE]
 > Interfaces not documented here are not considered public or stable,
 > and they may be removed or altered in incompatible ways at any time.
+
+We have organized the reference material along general functional areas.
+They are:
+
+- [Asynchronous I/O](aio/index.md)
+- [Asynchronous I/O for Providers](aio_provider/index.md)
+- General Utility Functions
+- Scalability Protocol Sockets
+- Scalability Protocol Contexts
+- Concurrency / Multi-threading
+- HTTP Server
+- HTTP Client
+- Streaming API
+- Statistics API
+- Legacy Compatibility
diff --git a/docs/reference/src/protocols/bus.md b/docs/reference/src/protocols/bus.md
new file mode 100644
index 00000000..8583ed65
--- /dev/null
+++ b/docs/reference/src/protocols/bus.md
@@ -0,0 +1,58 @@
+# BUS Protocol
+
+{{hi:protocol, _BUS_}}
+The {{i:_BUS_ protocol}} provides for building mesh networks where
+every peer is connected to every other peer.
+In this protocol, each message sent by a node is sent to every one of
+its directly connected peers.
+
+> [!TIP]
+> Messages are only sent to directly connected peers.
+> This means that in the event that a peer is connected indirectly, it will not
+> receive messages.
+> When using this protocol to build mesh networks, it
+> is therefore important that a _fully-connected_ mesh network be constructed.
+
+All message delivery in this pattern is {{i:best-effort}}, which means that
+peers may not receive messages.
+Furthermore, delivery may occur to some,
+all, or none of the directly connected peers.
+(Messages are not delivered when peer nodes are unable to receive.)
+Hence, send operations will never block; instead if the
+message cannot be delivered for any reason it is discarded.
+
+> [!TIP]
+> In order to minimize the likelihood of message loss, this protocol
+> should not be used for high throughput communications.
+> Furthermore, the more traffic _in aggregate_ that occurs across the topology,
+> the more likely that message loss is to occur.
+
+## Socket Operations
+
+The [`nng_bus0_open()`](../api/nng_bus_open.md) functions create a bus socket.
+This socket may be used to send and receive messages.
+Sending messages will attempt to deliver to each directly connected peer.
+
+## Protocol Versions
+
+Only version 0 of this protocol is supported.
+(At the time of writing, no other versions of this protocol have been defined.)
+
+## Protocol Options
+
+The _BUS_ protocol has no protocol-specific options.
+
+## Protocol Headers
+
+When using a _BUS_ socket in [raw mode](../overview/raw.md), received messages will
+contain the incoming [pipe](../api/nng_pipe.md) ID as the sole element in the header.
+If a message containing such a header is sent using a raw _BUS_ socket, then,
+the message will be delivered to all connected pipes _except_ the one
+identified in the header.
+This behavior is intended for use with [device](../api/nng_device.md)
+configurations consisting of just a single socket.
+Such configurations are useful in the creation of rebroadcasters, and this
+capability prevents a message from being routed back to its source.
+If no header is present, then a message is sent to all connected pipes.
+
+When using normal (cooked mode) _BUS_ sockets, no message headers are present.
diff --git a/docs/reference/src/protocols/index.md b/docs/reference/src/protocols/index.md
new file mode 100644
index 00000000..8d9f7317
--- /dev/null
+++ b/docs/reference/src/protocols/index.md
@@ -0,0 +1 @@
+# Protocols
diff --git a/docs/reference/src/transports/index.md b/docs/reference/src/transports/index.md
new file mode 100644
index 00000000..c7d74d80
--- /dev/null
+++ b/docs/reference/src/transports/index.md
@@ -0,0 +1,5 @@
+# Transports
+
+This chapter provides information about the various transports that _NNG_ supports.
+Transports may be thought of as different underlying communications
+technologies, such as TCP, Websockets, and so forth.
diff --git a/docs/reference/src/transports/tcp.md b/docs/reference/src/transports/tcp.md
new file mode 100644
index 00000000..54e36b67
--- /dev/null
+++ b/docs/reference/src/transports/tcp.md
@@ -0,0 +1,74 @@
+# TCP transport
+
+{{hi: transport, _tcp_}}
+The {{i:_tcp_ transport}} provides communication support between
+sockets across a {{i:TCP/IP}} network.
+
+Both IPv4 and IPv6 are supported when the underlying platform also supports it.
+
+This transport is built-in, so no extra steps to use it should be necessary.
+
+## URI Format
+
+{{hi:URI, `tcp://`}}
+This transport uses URIs using the scheme `tcp://`, followed by
+an IP address or hostname, followed by a colon and finally a
+TCP port number.{{hi:port number, TCP}}
+For example, to contact port 80 on the localhost either of the following URIs
+could be used: `tcp://127.0.0.1:80` or `tcp://localhost:80`.
+
+A URI may be restricted to IPv6 using the scheme `tcp6://`, and may
+be restricted to IPv4 using the scheme `tcp4://`.
+
+> [!NOTE]
+> Specifying `tcp6://` may not prevent IPv4 hosts from being used with
+> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with
+> listeners.
+> The details of this varies across operating systems.
+
+> [!NOTE]
+> Both `tcp6://` and `tcp4://` are specific to _NNG_, and might not
+> be understood by other implementations.
+
+> [!TIP]
+> We recommend using either numeric IP addresses, or names that are
+> specific to either IPv4 or IPv6 to prevent confusion and surprises.
+
+When specifying IPv6 addresses, the address must be enclosed in
+square brackets (`[]`) to avoid confusion with the final colon
+separating the port.
+
+For example, the same port 80 on the IPv6 loopback address (`::1`) would
+be specified as `tcp://[::1]:80`.
+
+The special value of 0 ({{i:`INADDR_ANY`}})
+can be used for a listener to indicate that it should listen on all
+interfaces on the host.
+A short-hand for this form is to either omit the address, or specify
+the asterisk (`*`) character.
+For example, the following three URIs are all equivalent,
+and could be used to listen to port 9999 on the host:
+
+1. `tcp://0.0.0.0:9999`
+2. `tcp://*:9999`
+3. `tcp://:9999`
+
+The entire URI must be less than `NNG_MAXADDRLEN` bytes long.
+
+## Socket Address
+
+When using an [`nng_sockaddr`](../api/nng_sockaddr.md) structure,
+the actual structure is either of type
+[`nng_sockaddr_in`](../api/nng_sockaddr_in.md) (for IPv4) or
+[`nng_sockaddr_in6`](../api/nng_sockaddr_in6.md) (for IPv6).
+
+## Transport Options
+
+The following transport options are supported by this transport,
+where supported by the underlying platform.
+
+- [`NNG_OPT_LOCADDR`](../api/nng_options.md#NNG_OPT_LOCADDR)
+- [`NNG_OPT_REMADDR`](../api/nng_options.md#NNG_OPT_REMADDR)
+- [`NNG_OPT_TCP_KEEPALIVE`](../api/nng_tcp_options.md#NNG_OPT_TCP_KEEPALIVE)
+- [`NNG_OPT_TCP_NODELAY`](../api/nng_tcp_options.md#NNG_OPT_TCP_NODELAY)
+- [`NNG_OPT_URL`](../api/nng_options.md#NNG_OPT_URL)