docs: consolidate misc chapter

5 files changed, 63 insertions, 105 deletions

diff --git a/docs/ref/api/memory.md b/docs/ref/api/memory.md
index 02748123..fb7ec18e 100644
--- a/docs/ref/api/memory.md
+++ b/docs/ref/api/memory.md
@@ -48,7 +48,7 @@ char *nng_strdup(const char *src);
 The {{i:`nng_strdup`}} duplicates the string _src_ and returns it.
 
 This is logically equivalent to using [`nng_alloc`][nng_alloc]
-to allocate a region of memory of `[c] strlen(s) + 1` bytes, and then
+to allocate a region of memory of `strlen(s) + 1` bytes, and then
 using `strcpy` to copy the string into the destination before
 returning it.
 
@@ -66,7 +66,7 @@ void nng_strfree(char *str);
 The {{i:`nng_strfree`}} function is a convenience function that
 can be used to deallocate strings allocated with [`nng_strdup`][nng_strdup].
 
-It is effectively the same as `[c] nng_free(strlen(str) + 1)`.
+It is effectively the same as `nng_free(strlen(str) + 1)`.
 
 [nng_alloc]: #allocate-memory
 [nng_free]: #deallocate-memory
diff --git a/docs/ref/api/misc.md b/docs/ref/api/misc.md
new file mode 100644
index 00000000..788c0b6d
--- /dev/null
+++ b/docs/ref/api/misc.md
@@ -0,0 +1,61 @@
+# Miscellaneous
+
+This chapter discusses some interfaces that don't really
+fit anywhere else.
+
+## Get Random Number
+
+```c
+uint32_t nng_random(void);
+```
+
+The {{i:`nng_random`}} returns a {{i:random number}}.
+The value returned is suitable for use with cryptographic functions such as
+key generation, and is obtained using platform-specific cryptographically strong random
+number facilities when available.
+
+## Create Socket Pair
+
+```c
+int nng_socket_pair(int fds[2]);
+```
+
+The `nng_socket_pair` function creates a pair of connected file descriptors.
+These file descriptors, which are returned in the _fds_ array, are suitable for
+use with the [Socket transport][socket].
+
+On POSIX platforms, this is a thin wrapper around the standard `socketpair` function,
+using the {{i:`AF_UNIX`}} family and the `SOCK_STREAM` socket type.
+{{footnote: At present only POSIX platforms implementing `socketpair` support this function.}}
+
+This will return zero on success, or an error number. On platforms that lack this
+capability, such as Windows, it will return `NNG_ENOTSUP`.
+
+> [!TIP]
+> This function may be useful for creating a shared connection between a parent process and
+> a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection.
+
+## Report Library Version
+
+```c
+const char * nng_version(void);
+```
+
+The {{i:`nng_version`}} function returns a human readable {{i:version number}}
+for _NNG_, formatted as a `NUL`-terminated string.
+
+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.)
+
+[socket]: ../tran/socket.md
diff --git a/docs/ref/api/util/nng_random.md b/docs/ref/api/util/nng_random.md
deleted file mode 100644
index b8a89d0e..00000000
--- a/docs/ref/api/util/nng_random.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# nng_random
-
-## NAME
-
-nng_random --- get random number
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-uint32_t nng_random(void);
-```
-
-## DESCRIPTION
-
-The {{i:`nng_random`}} returns a {{i: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
-number facilities when available.
-
-## RETURN VALUES
-
-Returns a random 32-bit value.
diff --git a/docs/ref/api/util/nng_socket_pair.md b/docs/ref/api/util/nng_socket_pair.md
deleted file mode 100644
index 454c15fc..00000000
--- a/docs/ref/api/util/nng_socket_pair.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# nng_socket_pair
-
-## NAME
-
-nng_socket_pair --- create a connected pair of BSD sockets
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-int nng_socket_pair(int fds[2]);
-```
-
-## DESCRIPTION
-
-The `nng_socket_pair` function creates a pair of connected BSD sockets.
-These sockets, which are returned in the _fds_ array, are suitable for
-use with the [BSD socket transport][socket].
-
-On POSIX platforms, this is a thin wrapper around the standard `socketpair` function,
-using the {{i:`AF_UNIX`}} family and the `SOCK_STREAM` socket type.
-{{footnote: At present only POSIX platforms implementing `socketpair` support this function.}}
-
-> [!TIP]
-> This function may be useful for creating a shared connection between a parent process and
-> a child process on UNIX platforms, without requiring the processes use a shared filesystem or TCP connection.
-
-## RETURN VALUES
-
-This function returns 0 on success, and non-zero otherwise.
-
-## ERRORS
-
-- `NNG_ENOMEM`: Insufficient memory exists.
-- `NNG_ENOTSUP`: This platform does not support socket pairs.
-
-## SEE ALSO
-
-[BSD Socket Transport][socket]
-
-[socket]: ../../tran/socket.md
diff --git a/docs/ref/api/util/nng_version.md b/docs/ref/api/util/nng_version.md
deleted file mode 100644
index 04a1dd1b..00000000
--- a/docs/ref/api/util/nng_version.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# nng_version
-
-## NAME
-
-nng_version --- report library version
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-const char * nng_version(void);
-```
-
-## DESCRIPTION
-
-The {{i:`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
-
-`NUL`-terminated string containing the library version number.