More org stuff

13 files changed, 105 insertions, 95 deletions

diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index 4ae2c79b..ba1454d8 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -9,6 +9,7 @@
 - [Protocols](./protocols/index.md)
 
   - [BUS](protocols/bus.md)
+  - [PUB](protocols/pub.md)
   - [REP](protocols/rep.md)
 
 - [Transports](./transports/index.md)
@@ -44,17 +45,18 @@
     - [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)
+  - [Utility Functions](api/util/index.md)
 
-    - [nng_alloc](api/nng_alloc.md)
-    - [nng_clock](api/nng_clock.md)
+    - [nng_alloc](api/util/nng_alloc.md)
+    - [nng_clock](api/util/nng_clock.md)
+    - [nng_free](api/util/nng_free.md)
+    - [nng_version](api/util/nng_version.md)
     - [nng_cv_alloc](api/nng_cv_alloc.md)
     - [nng_cv_free](api/nng_cv_free.md)
     - [nng_cv_until](api/nng_cv_until.md)
     - [nng_cv_wait](api/nng_cv_wait.md)
     - [nng_cv_wake](api/nng_cv_wake.md)
     - [nng_cv_wake1](api/nng_cv_wake1.md)
-    - [nng_free](api/nng_free.md)
 
   - [Context Functions](api/context.md)
 
diff --git a/docs/reference/src/api/aio/nng_aio_free.md b/docs/reference/src/api/aio/nng_aio_free.md
index c558535d..3d73dd7c 100644
--- a/docs/reference/src/api/aio/nng_aio_free.md
+++ b/docs/reference/src/api/aio/nng_aio_free.md
@@ -31,5 +31,4 @@ This can be useful to discard the _aio_ object from within the callback for the
 ## SEE ALSO
 
 [nng_aio_alloc()](nng_aio_alloc.md),
-[nng_aio_stop()](nng_aio_stop.md),
-[nng_aio](nng_aio.md)
+[nng_aio_stop()](nng_aio_stop.md)
diff --git a/docs/reference/src/api/aio/nng_aio_result.md b/docs/reference/src/api/aio/nng_aio_result.md
index fe6688fd..607f34d4 100644
--- a/docs/reference/src/api/aio/nng_aio_result.md
+++ b/docs/reference/src/api/aio/nng_aio_result.md
@@ -19,11 +19,12 @@ with the handle _aio_.
 If the operation was successful, then 0 is returned.
 Otherwise a non-zero error code is returned.
 
-NOTE: The return value from this function is undefined if the operation
-has not completed yet.
-Either call this from the handle's completion
-callback, or after waiting for the operation to complete with
-[`nng_aio_wait()`](nng_aio_wait.md).
+> [!NOTE]
+> The return value from this function is undefined if the operation
+> has not completed yet.
+> Either call this from the handle's completion
+> callback, or after waiting for the operation to complete with
+> [`nng_aio_wait()`](nng_aio_wait.md).
 
 ## RETURN VALUES
 
@@ -42,5 +43,4 @@ Various other return values are possible depending on the operation.
 [nng_aio_abort()](nng_aio_abort.md),
 [nng_aio_alloc()](nng_aio_alloc.md),
 [nng_aio_wait()](nng_aio_wait.md),
-[nng_strerror()](nng_strerror.md),
-[nng_aio](nng_aio.md),
+[nng_strerror()](../util/nng_strerror.md)
diff --git a/docs/reference/src/api/aio/nng_aio_wait.md b/docs/reference/src/api/aio/nng_aio_wait.md
index 52f5671e..be81378c 100644
--- a/docs/reference/src/api/aio/nng_aio_wait.md
+++ b/docs/reference/src/api/aio/nng_aio_wait.md
@@ -24,7 +24,7 @@ function will not be called until the callback has completed.
 
 > [!IMPORTANT]
 > This function should never be called from a function that itself
-> is a callback of an [`nng_aio`](nng_aio.md), either this one or any other.
+> is a callback of an [`nng_aio`](index.md), either this one or any other.
 > Doing so may result in a deadlock.
 
 ## SEE ALSO
diff --git a/docs/reference/src/api/aio_provider.md b/docs/reference/src/api/aio_provider.md
deleted file mode 100644
index cf5acce7..00000000
--- a/docs/reference/src/api/aio_provider.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Asynchronous I/O for Providers
-
-This section documents functions used when implementing I/O providers.
-
-I/O providers actually perform the operations that are linked to
-an [`nng_aio`](nng_aio.md) object.
-
-Most applications will not use the functions listed here.
-Applications the implement their own HTTP handler functions, or
-custom transport providers, might make use of these functions.
diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md
index 1541b541..fb27e444 100644
--- a/docs/reference/src/api/index.md
+++ b/docs/reference/src/api/index.md
@@ -10,14 +10,16 @@ the _NNG_ programming interface.
 We have organized the reference material along general functional areas.
 They are:
 
+- Sockets
+- Dialers, Listeners, and Pipes
+- Contexts
 - [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
+- Utility Functions
+- Threads and Synchronization
 - HTTP Client
-- Streaming API
-- Statistics API
+- HTTP Server
+- TLS Support
+- Connected Streams
+- Statistics
 - Legacy Compatibility
diff --git a/docs/reference/src/api/nng_aio.md b/docs/reference/src/api/nng_aio.md
deleted file mode 100644
index 667e785c..00000000
--- a/docs/reference/src/api/nng_aio.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# nng_aio
-
-## NAME
-
-nng_aio --- asynchronous I/O handle
-
-```c
-#include <nng/nng.h>
-
-typedef struct nng_aio nng_aio;
-```
-
-## DESCRIPTION
-
-An `nng_aio`{{hi:aio}} is an opaque structure used in conjunction with
-{{i:asynchronous I/O}} operations.
-Every asynchronous operation uses one of these structures, each of which
-can only be used with a single operation at a time.
-
-Asynchronous operations are performed without blocking calling application
-threads.
-Instead the application registers a callback function to be executed
-when the operation is complete (whether successfully or not).
-This callback will be executed exactly once.
-
-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)).
-
-It is also possible to initiate an asynchronous operation, and wait for it to
-complete [`nng_aio_wait()`](nng_aio_wait.md).
-
-These structures are created using the [`nng_aio_alloc()`](nng_aio_alloc.md),
-and destroyed using [`nng_aio_free()`](nng_aio_free.md).
-
-> [!IMPORTANT]
-> A given `nng_aio` can only have a single operation in progress
-> at any given time. Attempts to reuse an `nng_aio` while another
-> operation is in progress will generally cause a crash.
-
-## 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/general.md b/docs/reference/src/api/util/index.md
index a830d6bd..a830d6bd 100644
--- a/docs/reference/src/api/general.md
+++ b/docs/reference/src/api/util/index.md
diff --git a/docs/reference/src/api/nng_alloc.md b/docs/reference/src/api/util/nng_alloc.md
index 6cc4b21f..98f71fa5 100644
--- a/docs/reference/src/api/nng_alloc.md
+++ b/docs/reference/src/api/util/nng_alloc.md
@@ -19,7 +19,7 @@ at least _size_ bytes.
 The memory will be 64-bit aligned.
 
 The returned memory can be used to hold message buffers, in which
-case it can be directly passed to [`nng_send()`](nng_send.md) using
+case it can be directly passed to [`nng_send()`](../socket/nng_send.md) using
 the flag `NNG_FLAG_ALLOC`. Alternatively, it can be freed when no
 longer needed using [`nng_free()`](nng_free.md).
 
@@ -41,4 +41,4 @@ is returned.
 ## SEE ALSO
 
 [nng_free()](nng_free.md),
-[nng_send()](nng_send.md)
+[nng_send()](../socket/nng_send.md)
diff --git a/docs/reference/src/api/nng_clock.md b/docs/reference/src/api/util/nng_clock.md
index 37be0d0c..3653bfa2 100644
--- a/docs/reference/src/api/nng_clock.md
+++ b/docs/reference/src/api/util/nng_clock.md
@@ -29,7 +29,7 @@ very fine-grained values.
 > but different programs may have different references.
 
 This function is intended to help with setting appropriate
-timeouts using [`nng_cv_until()`](nng_cv_until.md).
+timeouts using [`nng_cv_until()`](../threads/nng_cv_until.md).
 
 ## RETURN VALUES
 
@@ -38,6 +38,6 @@ Milliseconds since reference time.
 ## SEE ALSO
 
 [nng_sleep_aio()](nng_sleep_aio.md),
-[nng_cv_until()](nng_cv_until.md),
+[nng_cv_until()](../threads/nng_cv_until.md),
 [nng_msleep()](nng_msleep.md),
 [nng_duration](nng_duration.md)
diff --git a/docs/reference/src/api/nng_free.md b/docs/reference/src/api/util/nng_free.md
index cc1d3308..ca527914 100644
--- a/docs/reference/src/api/nng_free.md
+++ b/docs/reference/src/api/util/nng_free.md
@@ -16,7 +16,7 @@ void nng_free(void *ptr, size_t size);
 
 The `nng_free()` function deallocates a memory region of size _size_,
 that was previously allocated by [`nng_alloc()`](nng_alloc.md) or
-[`nng_recv()`](nng_recv.md) with the `NNG_FLAG_ALLOC` flag.
+[`nng_recv()`](../socket/nng_recv.md) with the `NNG_FLAG_ALLOC` flag.
 
 > [!IMPORTANT]
 > It is very important that _size_ match the allocation size
diff --git a/docs/reference/src/api/util/nng_version.md b/docs/reference/src/api/util/nng_version.md
new file mode 100644
index 00000000..7cc10bdf
--- /dev/null
+++ b/docs/reference/src/api/util/nng_version.md
@@ -0,0 +1,36 @@
+# nng_version(3)
+
+## NAME
+
+nng_version - report library version
+
+## SYNOPSIS
+
+```c
+#include <nng/nng.h>
+
+const char * nng_version(void);
+```
+
+## DESCRIPTION
+
+The `nng_version()` function returns a human readable {{i:version number}}
+for _NNG_.
+
+Additionally, compile time version information is available
+via some predefined macros:
+
+- {{i:`NNG_MAJOR_VERSION`}}: Major version number.
+- {{i:`NNG_MINOR_VERSION`}}: Minor version number.
+- {{i:`NNG_PATCH_VERSION`}}: Patch version number.
+
+_NNG_ is developed and released using
+[Semantic Versioning 2.0](http://www.semver.org), and
+the version numbers reported refer to both the API and the library itself.
+(The {{i:ABI}} -- {{i:application binary interface}} -- between the
+library and the application is controlled in a similar, but different
+manner depending upon the link options and how the library is built.)
+
+## RETURN VALUES
+
+Null-terminated string containing the library version number.
diff --git a/docs/reference/src/protocols/pub.md b/docs/reference/src/protocols/pub.md
new file mode 100644
index 00000000..bd49b1d3
--- /dev/null
+++ b/docs/reference/src/protocols/pub.md
@@ -0,0 +1,40 @@
+# PUB Protocol
+
+The {{i:_PUB_ protocol}}{{hi:protocol, _PUB_} is one half of a {{i:publisher}}/subscriber pattern.
+In this pattern, a publisher sends data, which is broadcast to all
+subscribers.
+The subscribing applications only see the data to which
+they have subscribed.
+
+The _PUB_ protocol is the publisher side, and the
+[_SUB_](sub.md) protocol is the subscriber side.
+
+> [!NOTE]
+> In this implementation, the publisher delivers all messages to all
+> subscribers.
+> The subscribers maintain their own subscriptions, and filter them locally.
+> Thus, this pattern should not be used in an attempt to reduce bandwidth
+> consumption.
+
+The topics that subscribers subscribe to is just the first part of
+the message body.
+Applications should construct their messages accordingly.
+
+## Socket Operations
+
+The [`nng_pub0_open()`](../api/nng_pub_open.md) functions create a publisher socket.
+This socket may be used to send messages, but is unable to receive them.
+Attempts to receive messages will result in `NNG_ENOTSUP`.
+
+## 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 _PUB_ protocol has no protocol-specific options.
+
+## Protocol Headers
+
+The _PUB_ protocol has no protocol-specific headers.