Logging as a single chapter.

This is the direction we want to go with documentation.
Major areas of functionality should be one single chapter in
the API reference, which should make them far more usable
for people not already familiar with NNG.

This represents a substantial departure from UNIX man pages,
but many of our users are not used to working with UNIX man
pages anyway, and organization of man pages, while convenient
for reading with the legacy shell man command, fails on a number
of usability fronts.

6 files changed, 176 insertions, 225 deletions

diff --git a/docs/ref/api/log/index.md b/docs/ref/api/log/index.md
deleted file mode 100644
index b51bbe3b..00000000
--- a/docs/ref/api/log/index.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Logging
-
-These interfaces deal with message logs, which can be submitted
-by the application or by NNG itself.
-
-- [nng_log](./nng_log.md) --- Message logs
-- [nng_log_facility](./nng_log_facility.md) --- Facility for message logs
-- [nng_log_level](./nng_log_level.md) --- Severity level for message logs
-- [nng_log_logger](./nng_log_logger.md) --- Handler for log messages
diff --git a/docs/ref/api/log/nng_log.md b/docs/ref/api/log/nng_log.md
deleted file mode 100644
index 5d0db5a9..00000000
--- a/docs/ref/api/log/nng_log.md
+++ /dev/null
@@ -1,75 +0,0 @@
-# nng_log
-
-## NAME
-
-# nng_log --- log messages
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-void nng_log_err(const char *msgid, const char *msg, ...);
-void nng_log_warn(const char *msgid, const char *msg, ...);
-void nng_log_notice(const char *msgid, const char *msg, ...);
-void nng_log_info(const char *msgid, const char *msg, ...);
-void nng_log_debug(const char *msgid, const char *msg, ...);
-
-void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...);
-```
-
-## DESCRIPTION
-
-The {{i:`nng_log`}} functions are used to post a message to system or application {{i:logs}}.
-
-The first five forms all post a message at the severity indicated by the function name.
-The _msgid_ should be a short message identifier that should indicate the message in question.
-A `NULL` value for _msgid_ can be used as well.
-
-Message identifiers can be used to assist in filtering and classifying logged messages.
-These should uniquely identify the nature of the problem, whe possible, to assist in trouble-shooting.
-They should also be short.
-Eight characters or less is ideal, and more than sixteen is strongly discouraged.
-Message identifiers may not be displayed to human readers, or may not be displayed by default.
-Therefore, any information in the message identifier should also be in the log content.
-
-The message is formatted as if by `sprintf`, using `msg` as the format, and remaining arguments as arguments to the format.
-
-The final function, {{i:`nng_log_auth`}}, is used for posting authentication related messages which might be treated specially,
-such as be storing them in a separate (and presumably more secure) log file.
-It takes the severity as a level in _level_.
-The severity can be one of the following values:
-
-- `NNG_LOG_ERR`
-- `NNG_LOG_WARN`
-- `NNG_LOG_NOTICE`
-- `NNG_LOG_INFO`
-- `NNG_LOG_DEBUG`
-
-The message itself is handled according to the logging facility set up with [`nng_log_set_logger`][log_logger].
-Message delivery is best effort, and messages may be suppressed based on the priority set with [`nng_log_set_level`][log_level].
-
-Note that in order to get log messages, a suitable logger must be set using {{i:`nng_log_set_logger`}}.
-The default logger, {{i:`nng_null_logger`}} simply discards logged content.
-
-> [!TIP]
-> Applications should take care to limit the use of higher severity levels, as message logs
-> are potentially expensive, increase stress for end users and administrators, and further may
-> mask real problems if incorrectly over used.
->
-> Warnings and error messages should be concise and actionable, and notices should only
-> really be those things that are worthy of attention.
->
-> Informational and debug messages used during development should be removed when no longer
-> needed, as these messages can overwhelm logging subsystems and can reduce the
-> signal-to-noise value for the message logs, impairing the diagnostic value of the logs.
-
-## SEE ALSO
-
-[nng_log_facility][log_facility],
-[nng_log_level][log_level],
-[nng_log_logger][log_logger]
-
-[log_facility]: ./nng_log_facility.md
-[log_level]: ./nng_log_level.md
-[log_logger]: ./nng_log_logger.md
diff --git a/docs/ref/api/log/nng_log_facility.md b/docs/ref/api/log/nng_log_facility.md
deleted file mode 100644
index 28ffd05f..00000000
--- a/docs/ref/api/log/nng_log_facility.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# nng_log_facility
-
-## NAME
-
-nng_log_facility --- facility or category for log messages
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-typedef enum nng_log_facility {
-	NNG_LOG_USER   = 1,
-	NNG_LOG_DAEMON = 3,
-	NNG_LOG_AUTH   = 10,
-	NNG_LOG_LOCAL0 = 16,
-	NNG_LOG_LOCAL1 = 17,
-	NNG_LOG_LOCAL2 = 18,
-	NNG_LOG_LOCAL3 = 19,
-	NNG_LOG_LOCAL4 = 20,
-	NNG_LOG_LOCAL5 = 21,
-	NNG_LOG_LOCAL6 = 22,
-	NNG_LOG_LOCAL7 = 23,
-} nng_log_facility;
-
-void nng_log_set_facility(nng_log_facility facility);
-```
-
-## DESCRIPTION
-
-An {{i:`nng_log_facility`}} object represents a facility, which can be thought of as
-a category, for log message. Normally these are used to identify the source of the
-message. The facility values here correspond to those typical used with the UNIX
-`syslog` logging system.
-
-The `nng_log_set_facility` is used to set the _facility_ of the application posting logs,
-so that messages that are submitted by the application can be correctly attributed to
-the application itself. It may also help in message routing.
-
-Note that while the log levels used here overlap with common levels used by the
-`syslog` system found on POSIX systems, applications should not the numeric values
-being the same.
-
-## SEE ALSO
-
-[nng_log](./nng_log.md),
-[nng_log_level](./nng_log_level.md)
diff --git a/docs/ref/api/log/nng_log_level.md b/docs/ref/api/log/nng_log_level.md
deleted file mode 100644
index 7e7cadb2..00000000
--- a/docs/ref/api/log/nng_log_level.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# nng_log_level
-
-## NAME
-
-nng_log_level --- severity level for logging messages
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-typedef enum nng_log_level {
-	NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
-	NNG_LOG_ERR    = 3,
-	NNG_LOG_WARN   = 4,
-	NNG_LOG_NOTICE = 5,
-	NNG_LOG_INFO   = 6,
-	NNG_LOG_DEBUG  = 7
-} nng_log_level;
-
-void nng_log_set_level(nng_log_level level);
-nng_log_level nng_log_get_level(void);
-```
-
-## DESCRIPTION
-
-The `nng_log_level` type represents a severity for logged messages.
-These levels correspond to those found in the UNIX `syslog` subsystem,
-although applications should not depend upon the values being identical.
-
-The `nng_log_set_level` function is used to set the minimum severity to _level_ for processing log messages.
-Any messages with a less severe rating are not processed and simply are discarded.
-Use `NNG_LOG_NONE` to suppress all log messages.
-Use `NNG_LOG_DEBUG` to receive all log messages.
-
-The `nng_log_get_level` function returns the current log level, which can be useful
-to elide processing to create log content that will simply be discarded anyway.
-
-## RETURN VALUES
-
-The `nng_log_get_level` functions returns the current log level.
-
-## SEE ALSO
-
-[nng_log](./nng_log.md),
-[nng_log_facility](./nng_log_facility.md),
-[nng_log_logger](./nng_log_logger.md)
diff --git a/docs/ref/api/log/nng_log_logger.md b/docs/ref/api/log/nng_log_logger.md
deleted file mode 100644
index 26551091..00000000
--- a/docs/ref/api/log/nng_log_logger.md
+++ /dev/null
@@ -1,47 +0,0 @@
-# nng_log_logger
-
-## NAME
-
-nng_log_logger --- logging handler
-
-## SYNOPSIS
-
-```c
-#include <nng/nng.h>
-
-typedef void (*nng_logger)(nng_log_level level, nng_log_facility facility,
-    const char *msgid, const char *msg);
-
-void nng_null_logger(nng_log_level, nng_log_facility, const char *, const char *);
-void nng_stderr_logger(nng_log_level, nng_log_facility, const char *, const char *);
-void nng_system_logger(nng_log_level, nng_log_facility, const char *, const char *);
-
-void nng_log_set_logger(nng_logger logger);
-```
-
-## DESCRIPTION
-
-An {{i:`nng_logger`}}{{hi:logger}} is a function used as a handler to process logged messages.
-This is responsible for the final disposition of the logged messages.
-
-The {{i:`nng_log_set_logger`}} function is used to set the base logging function to _logger_.
-The _logger_ may be a user defined function to process log messages.
-Only a single logger may be registered at a time.
-If needed, the logger should make copies of either _msgid_ or _msg_, as they will not be valid after the logger returns.
-
-The {{i:`nng_null_logger`}} function is an implementation of `nng_logger` that simply discards the content.
-This is the default logger, so logging is disabled by default.
-
-The {{i:`nng_stderr_logger`}} function is an implementation that logs messages to the standard error stream.
-It will attempt to colorize messages by the severity, if the standard error is a terminal device.
-This can be supressed by setting either the `NO_COLOR` or `NNG_LOG_NO_COLOR` environment variables.
-
-The {{i:`nng_system_logger`}} attempts to use an appropriate system facility to log messages.
-For POSIX systems, this means using `syslog` to process the messages.
-For other systems the defauilt behavior may be the same as `nng_stderr_logger`.
-
-## SEE ALSO
-
-[nng_log](./nng_log.md),
-[nng_log_facility](./nng_log_facility.md),
-[nng_log_level](./nng_log_level.md)
diff --git a/docs/ref/api/logging.md b/docs/ref/api/logging.md
new file mode 100644
index 00000000..cbed636c
--- /dev/null
+++ b/docs/ref/api/logging.md
@@ -0,0 +1,176 @@
+# Logging
+
+This chapter describes the support for message logs.
+Both applications and _NNG_ itself can emit logs, which can be useful
+for application field support and debugging. Additionally applications
+can customize the handling of this logging as needed.
+
+Note that logging is disabled by default unless an application
+configures a suitable logger with [`nng_log_set_logger`][log_logger].
+
+## Submitting Logs
+
+```c
+void nng_log_err(const char *msgid, const char *msg, ...);
+void nng_log_warn(const char *msgid, const char *msg, ...);
+void nng_log_notice(const char *msgid, const char *msg, ...);
+void nng_log_info(const char *msgid, const char *msg, ...);
+void nng_log_debug(const char *msgid, const char *msg, ...);
+```
+
+These {{hi:`nng_log`}} functions inject a a message into the
+logging system, where it will be processed and potentially go to
+system logs, standard output, or procssed further.
+
+The _msgid_ is a short prefix that should uniquely identify the message,
+possibly also with some kind of category. It is recommended that
+strings between 8 and 16 charactes be used. As this may, but will not necessarily
+be displayed to the user, the content of the message should not appear
+solely in this field. A `NULL` value is permitted here, but that may
+make filtering the message or other automatic processing more difficult.
+
+The _msg_ is a `printf`-style format string, which is used to format the
+message content. The following arguments are consumed in the
+same manner as `printf`.
+
+> [!TIP]
+> Applications should take care to limit the use of higher severity levels, as message logs
+> are potentially expensive, increase stress for end users and administrators, and further may
+> mask real problems if incorrectly over used.
+>
+> Warnings and error messages should be concise and actionable, and notices should only
+> really be those things that are worthy of attention.
+>
+> Informational and debug messages used during development should be removed when no longer
+> needed, as these messages can overwhelm logging subsystems and can reduce the
+> signal-to-noise value for the message logs, impairing the diagnostic value of the logs.
+
+## Auth Logs
+
+```c
+void nng_log_auth(nng_log_level level, const char *msgid, const char *msg, ...);
+```
+
+The {{i:`nng_log_auth`}} function formats and injects a security related log message.
+("Auth" can indicate either "authentication" or "authorization".)
+The _level_ is a [log level][log_level].
+The _msgid_, _msg_, and any remaining arguments are processed in a fashion
+similar to the other [logging functions][submitting_logs], except that the
+logs may be are logged using the `NNG_LOG_AUTH` [facility][log_facility], and thus may be
+redirected or receive other special treatment.
+
+## Log Levels
+
+```c
+typedef enum nng_log_level nng_log_level;
+
+void nng_log_set_level(nng_log_level level);
+nng_log_level nng_log_get_level(void);
+```
+
+The {{i:`nng_log_level`}} type represents a severity for logged messages.
+These levels correspond to those found in the UNIX syslog subsystem,
+although applications should not depend upon the values being identical.
+
+The {{i:`nng_log_set_level`}} function sets the log level.
+Messages with a severity that is numerically greater than this (less-severe)
+will be discarded.
+
+The {{i:`nng_log_get_level`}} function returns the log level most recently
+set by `nng_log_set_level` or the default
+if that function has not been called.
+
+The log levels are defined as follows:
+
+```c
+typedef enum nng_log_level {
+	NNG_LOG_NONE   = 0, // used for filters only, NNG suppresses these
+	NNG_LOG_ERR    = 3,
+	NNG_LOG_WARN   = 4,
+	NNG_LOG_NOTICE = 5,
+	NNG_LOG_INFO   = 6,
+	NNG_LOG_DEBUG  = 7
+} nng_log_level;
+```
+
+The value `NNG_LOG_NONE` may be useful to suppress message logs altogether.
+
+The default level is typically `NNG_LOG_NOTICE`, but applications should
+select a value rather than relying upon the default.
+
+## Log Facilities
+
+```c
+typedef enum nng_log_facility
+
+void nng_log_set_facility(nng_log_facility facility);
+```
+
+Logging facilities are used to indicate the source of a log message,
+and may be useful in routing and processing these logs.
+Traditionally these are used with the UNIX `syslog` system, and
+the values here represent some (but not all) of the values found there.
+
+The following values are defined:
+
+```c
+typedef enum nng_log_facility {
+	NNG_LOG_USER   = 1,
+	NNG_LOG_DAEMON = 3,
+	NNG_LOG_AUTH   = 10,
+	NNG_LOG_LOCAL0 = 16,
+	NNG_LOG_LOCAL1 = 17,
+	NNG_LOG_LOCAL2 = 18,
+	NNG_LOG_LOCAL3 = 19,
+	NNG_LOG_LOCAL4 = 20,
+	NNG_LOG_LOCAL5 = 21,
+	NNG_LOG_LOCAL6 = 22,
+	NNG_LOG_LOCAL7 = 23,
+} nng_log_facility;
+```
+
+The {{i:`nng_log_set_facility`}} function can be used to
+set the facility that the application will use when emitting log
+messages. This should be called as part of initialization of the
+application, if logging is to be used.
+
+The default facility is typically `NNG_LOG_USER`, but applications should
+select a value rather than relying upon the default.
+
+## Log Handlers
+
+```c
+typedef void (*nng_logger)(nng_log_level level, nng_log_facility facility,
+    const char *msgid, const char *msg);
+
+void nng_null_logger(nng_log_level, nng_log_facility, const char *, const char *);
+void nng_stderr_logger(nng_log_level, nng_log_facility, const char *, const char *);
+void nng_system_logger(nng_log_level, nng_log_facility, const char *, const char *);
+
+void nng_log_set_logger(nng_logger logger);
+```
+
+{{i:Log handlers}} are responsible for actually processing the logged messages.
+
+The {{i:`nng_log_set_logger`}} function installs the named _logger_, of type {{i:`nng_logger`}},
+as the log handler. The function _logger_ will be called when any message is meant to
+be processed. (Messages are first filtered by [severity][log_level], then formatted,
+before calling the logger.)
+
+Any previously installed logger is replaced by _logger_.
+
+The {{i:`nng_null_logger`}} function is an implementation of `nng_logger` that simply discards the content.
+This is the default logger, so logging is disabled by default.
+
+The {{i:`nng_stderr_logger`}} function is an implementation that logs messages to the standard error stream.
+It will attempt to colorize messages by the severity, if the standard error is a terminal device.
+This can be suppressed by setting either the `NO_COLOR` or `NNG_LOG_NO_COLOR` environment variables.
+
+The {{i:`nng_system_logger`}} attempts to use an appropriate system facility to log messages.
+For POSIX systems, this means using `syslog` to process the messages.
+For other systems the defauilt behavior may be the same as `nng_stderr_logger`.
+
+[log_level]: #log-levels
+[log_facility]: #log-facilities
+[log_logger]: #log-handlers
+[submitting_logs]: #submitting-logs