More content changes.

12 files changed, 88 insertions, 116 deletions

diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md
index ba1454d8..f029f8fb 100644
--- a/docs/reference/src/SUMMARY.md
+++ b/docs/reference/src/SUMMARY.md
@@ -19,6 +19,12 @@
 
 - [API Reference](./api/index.md)
 
+  - [Sockets](api/socket/index.md)
+
+    - [nng_bus_open](api/socket/nng_bus_open.md)
+    - [nng_close](api/socket/nng_close.md)
+    - [nng_pub_open](api/socket/nng_pub_open.md)
+
   - [Asynchronous I/O](./api/aio/index.md)
 
     - [nng_aio_abort](api/aio/nng_aio_abort.md)
@@ -50,13 +56,18 @@
     - [nng_alloc](api/util/nng_alloc.md)
     - [nng_clock](api/util/nng_clock.md)
     - [nng_free](api/util/nng_free.md)
+    - [nng_random](api/util/nng_random.md)
+    - [nng_strerror](api/util/nng_strerror.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)
+
+  - [Threads and Synchronization](api/threads/index.md)
+
+    - [nng_cv_alloc](api/threads/nng_cv_alloc.md)
+    - [nng_cv_free](api/threads/nng_cv_free.md)
+    - [nng_cv_until](api/threads/nng_cv_until.md)
+    - [nng_cv_wait](api/threads/nng_cv_wait.md)
+    - [nng_cv_wake](api/threads/nng_cv_wake.md)
+    - [nng_cv_wake1](api/threads/nng_cv_wake1.md)
 
   - [Context Functions](api/context.md)
 
@@ -73,11 +84,6 @@
     - [nng_ctx_set](api/nng_ctx_set.md)
     - [nng_ctx_setopt](api/nng_ctx_setopt.md)
 
-  - [Protocol Sockets](api/protocol.md)
-
-    - [nng_bus_open](api/nng_bus_open.md)
-    - [nng_close](api/nng_close.md)
-
   - [Legacy Compatibility](api/compat/index.md)
 
 - [Index](./indexing.md)
diff --git a/docs/reference/src/api/aio/nng_aio_set_timeout.md b/docs/reference/src/api/aio/nng_aio_set_timeout.md
index b0bab9ab..e5ac3e8e 100644
--- a/docs/reference/src/api/aio/nng_aio_set_timeout.md
+++ b/docs/reference/src/api/aio/nng_aio_set_timeout.md
@@ -33,7 +33,7 @@ timeout is used.
 The `nng_aio_set_expire()` function is similar to `nng_aio_set_timeout()`, but sets
 an absolute expiration time based on the system clock. The _expiration_
 is expressed as a number of milliseconds since some point in the past.
-The [`nng_clock()`](nng_clock.md) function can be used to determine
+The [`nng_clock()`](../util/nng_clock.md) function can be used to determine
 the current value of the clock.
 
 > [!TIP]
@@ -50,4 +50,4 @@ or absolute timeout.
 
 [nng_aio_cancel()](nng_aio_cancel.md),
 [nng_aio_result()](nng_aio_result.md),
-[nng_duration](nng_duration)
+[nng_clock()](../util/nng_clock.md)
diff --git a/docs/reference/src/api/index.md b/docs/reference/src/api/index.md
index fb27e444..a88c44f1 100644
--- a/docs/reference/src/api/index.md
+++ b/docs/reference/src/api/index.md
@@ -15,7 +15,7 @@ They are:
 - Contexts
 - [Asynchronous I/O](aio/index.md)
 - [Asynchronous I/O for Providers](aio_provider/index.md)
-- Utility Functions
+- [Utility Functions](util/index.md)
 - Threads and Synchronization
 - HTTP Client
 - HTTP Server
diff --git a/docs/reference/src/api/socket/index.md b/docs/reference/src/api/socket/index.md
index 990b7cbb..8bd82b7d 100644
--- a/docs/reference/src/api/socket/index.md
+++ b/docs/reference/src/api/socket/index.md
@@ -1 +1,7 @@
 # Protocol Sockets
+
+## See Also
+
+[nng_bus_open()](nng_bus_open.md)
+[nng_close()](nng_close.md)
+[nng_pub_open()](nng_pub_open.md)
diff --git a/docs/reference/src/api/socket/nng_bus_open.md b/docs/reference/src/api/socket/nng_bus_open.md
index a579acfb..fd56455b 100644
--- a/docs/reference/src/api/socket/nng_bus_open.md
+++ b/docs/reference/src/api/socket/nng_bus_open.md
@@ -2,7 +2,7 @@
 
 ## NAME
 
-nng_bus_open --- create bus socket
+nng_bus_open --- create _BUS_ socket
 
 ## SYNOPSIS
 
@@ -17,10 +17,10 @@ int nng_bus0_open_raw(nng_socket *s);
 
 ## DESCRIPTION
 
-The `nng_bus0_open()` function creates a [_BUS_](../protocols/bus.md) version 0
+The `nng_bus0_open()` function creates a [_BUS_](../../protocols/bus.md) version 0
 [socket](nng_socket.md) and returns it at the location pointed to by _s_.
 
-The `nng_bus0_open_raw()` function creates a [_BUS_](../protocols/bus.md) version 0
+The `nng_bus0_open_raw()` function creates a [_BUS_](../../protocols/bus.md) version 0
 [socket](nng_socket.md) in
 [raw](../overview/raw.md) mode, and returns it at the location pointed to by _s_.
 
@@ -35,6 +35,5 @@ These functions return 0 on success, and non-zero otherwise.
 
 ## SEE ALSO
 
-[nng_socket()](nng_socket.md),
-[BUS protocol](../protocols/bus.md),
-[RAW mode](../overview/raw.md)
+[BUS protocol](../../protocols/bus.md),
+[RAW mode](../../overview/raw.md)
diff --git a/docs/reference/src/api/socket/nng_pub_open.md b/docs/reference/src/api/socket/nng_pub_open.md
index c9f3b5b5..987718f4 100644
--- a/docs/reference/src/api/socket/nng_pub_open.md
+++ b/docs/reference/src/api/socket/nng_pub_open.md
@@ -1,53 +1,39 @@
-= nng_pub_open(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
+# nng_pub_open()
 
-== NAME
+## NAME
 
-nng_pub_open - create pub socket
+nng_pub_open --- create _PUB_ socket
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source,c]
-----
+```c
 #include <nng/nng.h>
 #include <nng/protocol/pubsub0/pub.h>
 
 int nng_pub0_open(nng_socket *s);
 
 int nng_pub0_open_raw(nng_socket *s);
-----
+```
 
 == DESCRIPTION
 
-The `nng_pub0_open()` function creates a xref:nng_pub.7.adoc[_pub_] version 0
-xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_.
+The `nng_pub0_open()` function creates a [_PUB_](../../protocols/pub.md) version 0
+[socket](nng_socket.md) and returns it at the location pointed to by _s_.
 
-The `nng_pub0_open_raw()` function creates a xref:nng_pub.7.adoc[_pub_] version 0
-xref:nng_socket.5.adoc[socket] in
-xref:nng.7.adoc#raw_mode[raw] mode and returns it at the location pointed to by _s_.
+The `nng_pub0_open_raw()` function creates a [_PUB_](../../protocols/pub.md) version 0
+[socket](nng_socket.md) in
+[raw](../../overview/raw.md) mode and returns it at the location pointed to by _s_.
 
-== RETURN VALUES
+## RETURN VALUES
 
 These functions return 0 on success, and non-zero otherwise.
 
-== ERRORS
+## ERRORS
 
-[horizontal]
-`NNG_ENOMEM`:: Insufficient memory is available.
-`NNG_ENOTSUP`:: The protocol is not supported.
+- `NNG_ENOMEM`: Insufficient memory is available.
+- `NNG_ENOTSUP`: The protocol is not supported.
 
-== SEE ALSO
+## SEE ALSO
 
-[.text-left]
-xref:nng_socket.5.adoc[nng_socket(5)],
-xref:nng_pub.7.adoc[nng_pub(7)],
-xref:nng_sub.7.adoc[nng_sub(7)],
-xref:nng.7.adoc[nng(7)]
+[PUB Protocol](../../protocols/pub.md),
+[SUB Protocol](../../protocols/sub.md)
diff --git a/docs/reference/src/api/threads/nng_cv_until.md b/docs/reference/src/api/threads/nng_cv_until.md
index 34669953..620b46b7 100644
--- a/docs/reference/src/api/threads/nng_cv_until.md
+++ b/docs/reference/src/api/threads/nng_cv_until.md
@@ -19,7 +19,7 @@ The `nng_cv_until()` waits until either the condition variable _cv_ is signaled
 by another thread calling either
 [`nng_cv_wake()`](nng_cv_wake.md) or
 [`nng_cv_wake1()`](nng_cv_wake1.md), or the system clock (as tracked
-by [`nng_clock()`](nng_clock.md)) reaches _when_.
+by [`nng_clock()`](../util/nng_clock.md)) reaches _when_.
 
 The caller must have have ownership of the mutex that was used when
 _cv_ was allocated.
@@ -65,7 +65,7 @@ The following example demonstrates use of this function:
 
 ## SEE ALSO
 
-[nng_clock()](nng_clock.md),
+[nng_clock()](../util/nng_clock.md),
 [nng_cv_alloc()](nng_cv_alloc.md),
 [nng_cv_wait()](nng_cv_wait.md),
 [nng_cv_wake()](nng_cv_wake.md),
diff --git a/docs/reference/src/api/util/index.md b/docs/reference/src/api/util/index.md
index a830d6bd..2ca0bc0b 100644
--- a/docs/reference/src/api/util/index.md
+++ b/docs/reference/src/api/util/index.md
@@ -1 +1,9 @@
 # General Purpose Functions
+
+# See Also
+
+[nng_alloc()](nng_alloc.md),
+[nng_clock()](nng_clock.md),
+[nng_free()](nng_free.md),
+[nng_random()](nng_random.md),
+[nng_version()](nng_version.md)
diff --git a/docs/reference/src/api/util/nng_clock.md b/docs/reference/src/api/util/nng_clock.md
index 3653bfa2..2b42b158 100644
--- a/docs/reference/src/api/util/nng_clock.md
+++ b/docs/reference/src/api/util/nng_clock.md
@@ -29,7 +29,8 @@ 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()`](../threads/nng_cv_until.md).
+timeouts using [`nng_cv_until()`](../threads/nng_cv_until.md)
+or [`nng_aio_set_expire()`](../aio/nng_aio_set_timeout.md).
 
 ## RETURN VALUES
 
diff --git a/docs/reference/src/api/util/nng_random.md b/docs/reference/src/api/util/nng_random.md
index 3f8ac39e..b358dfb6 100644
--- a/docs/reference/src/api/util/nng_random.md
+++ b/docs/reference/src/api/util/nng_random.md
@@ -1,45 +1,26 @@
-= nng_random(3supp)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
+# nng_random()
 
-== NAME
+## NAME
 
-nng_random - get random number
+nng_random --- get random number
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```c
 #include <nng/nng.h>
 #include <nng/supplemental/util/platform.h>
 
 uint32_t nng_random(void);
-----
+```
 
-== DESCRIPTION
+## DESCRIPTION
 
 The `nng_random()` returns a random number.
 The value returned is suitable for use with cryptographic functions such as
 key generation.
-The value is obtained using platform specific cryptographically strong random
+The value is obtained using platform-specific cryptographically strong random
 number facilities when available.
 
-== RETURN VALUES
+## RETURN VALUES
 
-Random number.
-
-== ERRORS
-
-None.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng.7.adoc[nng(7)]
+Returns a random 32-bit value.
diff --git a/docs/reference/src/api/util/nng_strerror.md b/docs/reference/src/api/util/nng_strerror.md
index 145fd0bc..3315651a 100644
--- a/docs/reference/src/api/util/nng_strerror.md
+++ b/docs/reference/src/api/util/nng_strerror.md
@@ -1,48 +1,33 @@
-= nng_strerror(3)
-//
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
-// Copyright 2018 Capitar IT Group BV <info@capitar.com>
-//
-// This document is supplied under the terms of the MIT License, a
-// copy of which should be located in the distribution where this
-// file was obtained (LICENSE.txt).  A copy of the license may also be
-// found online at https://opensource.org/licenses/MIT.
-//
+# nng_strerror()
 
-== NAME
+## NAME
 
-nng_strerror - return an error description
+nng_strerror --- return an error description
 
-== SYNOPSIS
+## SYNOPSIS
 
-[source, c]
-----
+```c
 #include <nng/nng.h>
 
 const char * nng_strerror(int err);
-----
+```
 
-== DESCRIPTION
+## DESCRIPTION
 
 The `nng_strerror()` returns the human-readable description of the
 given error in `err`.
 
-NOTE: The returned error message is provided in US English, but in the
+The returned error message is provided in US English, but in the
 future locale-specific strings may be presented instead.
 
-NOTE: The specific strings associated with specific error messages are
-subject to change.
-Therefore applications must not depend on the message,
-but may use them verbatim when supplying information to end-users, such
-as in diagnostic messages or log entries.
+> [!NOTE]
+> The specific strings associated with specific error messages are
+> subject to change.
+> Therefore applications must not depend on the message,
+> but may use them verbatim when supplying information to end-users, such
+> as in diagnostic messages or log entries.
 
-== RETURN VALUES
+## RETURN VALUES
 
 This function returns the human-readable error message, terminated
 by a `NUL` byte.
-
-== SEE ALSO
-
-[.text-left]
-xref:libnng.3.adoc[libnng(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/reference/src/api/util/nng_version.md b/docs/reference/src/api/util/nng_version.md
index 7cc10bdf..20ae094b 100644
--- a/docs/reference/src/api/util/nng_version.md
+++ b/docs/reference/src/api/util/nng_version.md
@@ -2,7 +2,7 @@
 
 ## NAME
 
-nng_version - report library version
+nng_version --- report library version
 
 ## SYNOPSIS
 
@@ -33,4 +33,4 @@ manner depending upon the link options and how the library is built.)
 
 ## RETURN VALUES
 
-Null-terminated string containing the library version number.
+`NUL`-terminated string containing the library version number.