nng_opts_parse and nng_socket_pair

3 files changed, 75 insertions, 133 deletions

diff --git a/docs/man/nng_socket_pair.3supp.adoc b/docs/man/nng_socket_pair.3supp.adoc
deleted file mode 100644
index 68b4a943..00000000
--- a/docs/man/nng_socket_pair.3supp.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-= nng_socket_pair(3supp)
-//
-// Copyright 2023 Staysail Systems, Inc. <info@staysail.tech>
-//
-// 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.
-//
-
-== NAME
-
-nng_socket_pair - create a connected pair of BSD sockets
-
-== SYNOPSIS
-
-[source, c]
-----
-#include <nng/nng.h>
-#include <nng/supplemental/util/platform.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 xref:nng_socket.7.adoc[_socket_] transport.
-
-On POSIX platforms, this is a thin wrapper around the standard `socketpair()` function,
-using the `AF_UNIX` family and the `SOCK_STREAM` socket type.
-
-NOTE: At present only POSIX platforms implementing `socketpair()` are supported with 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
-
-[horizontal]
-`NNG_ENOMEM`:: Insufficient memory exists.
-`NNG_ENOTSUP`:: This platform does not support socket pairs.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_socket.7.adoc[nng_socket(7)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/man/nng_opts_parse.3supp.adoc b/docs/ref/util/nng_opts_parse.adoc
index beb9e1bf..93bf30e2 100644
--- a/docs/man/nng_opts_parse.3supp.adoc
+++ b/docs/ref/util/nng_opts_parse.adoc
@@ -1,22 +1,10 @@
-= nng_opts_parse(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_opts_parse
 
-== NAME
+Parse command line options.
 
-nng_opts_parse - parse command line options
+### Synopsis
 
-== SYNOPSIS
-
-[source, c]
-----
+```c
 #include <nng/nng.h>
 #include <nng/supplemental/util/options.h>
 
@@ -27,41 +15,31 @@ typedef struct nng_optspec {
     bool        o_arg;   // Option takes an argument if true
 } nng_optspec;
 
-int nng_opts_parse(int argc, char *const *argv, const nng_optspec *spec, int *val, char **arg, int *idx);
-----
+int nng_opts_parse(int argc, char *const *argv,
+                   const nng_optspec *spec, int *val, char **arg, int *idx);
+```
 
-== DESCRIPTION
+### Description
 
-The `nng_opts_parse()` is function is a supplemental function intended to
-facilitate parsing command line arguments.
-This function exists largely to stand in for `getopt()` from POSIX
-systems, but it is available everywhere that _NNG_ is, and it includes
-some capabilities missing from `getopt()`.
+The `nng_opts_parse` is function is a supplemental function intended to facilitate parsing command line arguments.
+This function is a substitute for `getopt` from POSIX systems, and it is available everywhere that _NNG_ is.
+It also includes some capabilities missing from `getopt`.
 
-The function parses arguments from `main()` (using _argc_ and _argv_),
-starting at the index referenced by _idx_.
+The function parses arguments from `main` (using _argc_ and _argv_), starting at the index referenced by _idx_.
 (New invocations typically set the value pointed to by _idx_ to 1.)
 
 Options are parsed as specified by _spec_ (see <<Option Specification>>.)
-The value of the parsed option will be stored at the address indicated by
-_val_, and the value of _idx_ will be incremented to reflect the next
-option to parse.
+The value of the parsed option will be stored at the address indicated by _val_, and the value of _idx_ will be incremented to reflect the next option to parse.
 
-TIP: For using this to parse command-line like strings that do not include
-the command name itself, set the value referenced by _idx_ to zero
-instead of one.
+TIP: For using this to parse command-line like strings that do not include the command name itself, set the value referenced by _idx_ to zero instead of one.
 
-If the option had an argument, a pointer to that is returned at the address
-referenced by _arg_.
+If the option had an argument, a pointer to that is returned at the address referenced by _arg_.
 
-This function should be called repeatedly, until it returns either -1
-(indicating the end of options is reached) or a non-zero error code is
-returned.
+This function should be called repeatedly, until it returns either -1 (indicating the end of options is reached) or a non-zero error code is returned.
 
-=== Option Specification
+#### Option Specification
 
-The calling program must first create an array of `nng_optspec` structures
-describing the options to be supported.
+The calling program must first create an array of `nng_optspec` structures describing the options to be supported.
 This structure has the following members:
 
 `o_name`::
@@ -80,50 +58,37 @@ This structure has the following members:
 `o_val`::
 
   This is a numeric value that is unique to this option.
-  This value is assigned by the application program, and must be non-zero
-  for a valid option.
-  If this is zero, then it indicates the end of the specifications, and the
-  rest of this structure is ignored.
-  The value will be returned to the caller in _val_ by `nng_opts_parse()` when
-  this option is parsed from the command line.
+  This value is assigned by the application program, and must be non-zero for a valid option.
+  If this is zero, then it indicates the end of the specifications, and the rest of this structure is ignored.
+  The value will be returned to the caller in _val_ by `nng_opts_parse` when this option is parsed from the command line.
 
 `o_arg`::
 
   This value should be set to `true` if the option should take an argument.
 
-=== Long Options
+#### Long Options
 
-Long options are parsed from the _argv_ array, and are indicated when
-the element being scanned starts with two dashes.
-For example, the "verbose" option would be specified as `--verbose` on
-the command line.
-If a long option takes an argument, it can either immediately follow
-the option as the next element in _argv_, or it can be appended to
-the option, separated from the option by an equals sign (`=`) or a
-colon (`:`).
+Long options are parsed from the _argv_ array, and are indicated when the element being scanned starts with two dashes.
+For example, the "verbose" option would be specified as `--verbose` on the command line.
+If a long option takes an argument, it can either immediately follow the option as the next element in _argv_, or it can be appended to
+the option, separated from the option by an equals sign (`=`) or a colon (`:`).
 
-=== Short Options
+#### Short Options
 
-Short options appear by themselves in an _argv_ element, prefixed by a
-dash (`-`).
-If the short option takes an argument, it can either be appended in the
-same element of _argv_, or may appear in the next _argv_ element.
+Short options appear by themselves in an _argv_ element, prefixed by a dash (`-`).
+If the short option takes an argument, it can either be appended in the same element of _argv_, or may appear in the next _argv_ element.
 
-NOTE: Option clustering, where multiple options can be crammed together in
-a single _argv_ element, is not supported by this function (yet).
+NOTE: Option clustering, where multiple options can be grouped together in a single _argv_ element, is not supported by this function.
 
-=== Prefix Matching
+#### Prefix Matching
 
-When using long options, the parser will match if it is equal to a prefix
-of the `o_name` member of a option specification, provided that it do so
-unambiguously (meaning it must not match any other option specification.)
+When using long options, the parser will match if it is equal to a prefix of the `o_name` member of a option specification, provided that it do so unambiguously (meaning it must not match any other option specification.)
 
-== EXAMPLE
+### Example
 
 The following program fragment demonstrates this function.
 
-[source, c]
-----
+```c
     enum { OPT_LOGFILE, OPT_VERBOSE };
     char *logfile; // options to be set
     bool verbose;
@@ -164,22 +129,15 @@ The following program fragment demonstrates this function.
         printf("Options error: %s\n", nng_strerror(rv));
         exit(1);
     }
-----
+```
 
-== RETURN VALUES
+### Return Values
 
-This function returns 0 if an option parsed correctly, -1 if
-no more options are available to be parsed, or an error number otherwise.
+This function returns 0 if an option parsed correctly, -1 if no more options are available to be parsed, or an error number otherwise.
 
-== ERRORS
+### Errors
 
 [horizontal]
 `NNG_EAMBIGUOUS`:: Parsed option matches more than one specification.
 `NNG_ENOARG`:: Option requires an argument, but one is not present.
 `NNG_EINVAL`:: An invalid (unknown) argument is present.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_strerror.3.adoc[nng_strerror(3)],
-xref:nng.7.adoc[nng(7)]
diff --git a/docs/ref/util/nng_socket_pair.adoc b/docs/ref/util/nng_socket_pair.adoc
new file mode 100644
index 00000000..04809618
--- /dev/null
+++ b/docs/ref/util/nng_socket_pair.adoc
@@ -0,0 +1,37 @@
+## nng_socket_pair
+
+Create a connected pair of BSD sockets.
+
+### Synopsis
+
+```c
+#include <nng/nng.h>
+#include <nng/supplemental/util/platform.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 xref:../tran/socket.adoc[_socket_] transport.
+
+On POSIX platforms, this is a thin wrapper around the standard `socketpair` function, using the `AF_UNIX` family and the `SOCK_STREAM` socket type.
+
+NOTE: At present only POSIX platforms implementing `socketpair` are supported with 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
+
+[horizontal]
+`NNG_ENOMEM`:: Insufficient memory exists.
+`NNG_ENOTSUP`:: This platform does not support socket pairs.
+
+### See Also
+
+xref:../tran/socket.adoc[BSD Socket Transport]