log documentation converted to mdbook.

11 files changed, 227 insertions, 258 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index a6541b52..4183c316 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -264,16 +264,16 @@ to observe program behaviors and as an aid in troubleshooting.
 // |xref:nng_url_parse.3.adoc[nng_url_parse()]|create URL structure from string
 // |===
 
-=== Logging Support
+// === Logging Support
 
-Common functionality for message logging.
+// Common functionality for message logging.
 
-|===
-|xref:nng_log.3.adoc[nng_log()]|log a message
-|xref:nng_log_facility.3.adoc[nng_log_set_facility()]|set log facility
-|xref:nng_log_level.3.adoc[nng_log_set_level()]|set log level
-|xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler
-|===
+// |===
+// |xref:nng_log.3.adoc[nng_log()]|log a message
+// |xref:nng_log_facility.3.adoc[nng_log_set_facility()]|set log facility
+// |xref:nng_log_level.3.adoc[nng_log_set_level()]|set log level
+// |xref:nng_log_logger.3.adoc[nng_log_set_logger()]|set logging handler
+// |===
 
 === Supplemental API
 
diff --git a/docs/man/nng_log.3.adoc b/docs/man/nng_log.3.adoc
deleted file mode 100644
index 358264c2..00000000
--- a/docs/man/nng_log.3.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-= nng_log(3)
-//
-// Copyright 2024 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_log - log messages
-
-== SYNOPSIS
-
-[source, 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
-
-These functions are used to post a message to system or application 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_ canbe used as well.
-
-Message identifiers can be used to assist in filtering logs.
-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.
-
-The message is formatting as if by `sprintf`, using `msg` as the format, and remaining arguments as arguments to the format.
-
-The final function, `nng_log_auth`, is used for posting authentication related messages which might be treated specially, such as be storing them in a separate secured 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 xref:nng_mg_set_logger.3.adoc[`nng_log_set_logger`].
-Message delivery is best effort, and messages may be suppressed based on the priority set with xref:nng_log_set_level.3.adoc[`nng_log_set_level`].
-
-Note that in order to get log messages, a suitable logger must be set using `nng_log_set_logger`.
-The default logger, `nng_null_logger` simply discards logged content.
-
-== SEE ALSO
-
-xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)],
-xref:nng_log_set_level.3.adoc[nng_log_set_level(3)],
-xref:nng_log_set_logger.3.adoc[nng_log_set_logger(3)]
diff --git a/docs/man/nng_log_get_level.3.adoc b/docs/man/nng_log_get_level.3.adoc
deleted file mode 100644
index 7ff90906..00000000
--- a/docs/man/nng_log_get_level.3.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-= nng_log_get_level(3)
-//
-// Copyright 2024 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_log_get_level - get minimum level for logging messagse
-
-== SYNOPSIS
-
-[source, 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;
-
-nng_log_level nng_log_set_level(void);
-----
-
-== DESCRIPTION
-
-The `nng_log_get_level` function is used to get the minimum severity to _level_ for processing log messages.
-The intended use case is to avoid expensive operations used solely to provide debugging information in logs,
-if the logged content would merely be discarded.
-
-== SEE ALSO
-
-xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)],
-xref:nng_log_set_level.3.adoc[nng_log_set_level(3)]
diff --git a/docs/man/nng_log_set_facility.3.adoc b/docs/man/nng_log_set_facility.3.adoc
deleted file mode 100644
index ecd6ab76..00000000
--- a/docs/man/nng_log_set_facility.3.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-= nng_log_set_facility(3)
-//
-// Copyright 2024 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_log_set_facility - set facility used for log messages
-
-== SYNOPSIS
-
-[source, 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
-
-The `nng_log_set_facility` is used to set the _facility_ of the application posting logs.
-This is used to assist with directing log content when handled by services such as `syslog`.
-
-Note that while the log levels used here overlap with common levels used by the syslog facility on POSIX systems, applications should not rely on this.
-
-== SEE ALSO
-
-xref:nng_log_set_level.3.adoc[nng_log_set_level(3)]
diff --git a/docs/man/nng_log_set_level.3.adoc b/docs/man/nng_log_set_level.3.adoc
deleted file mode 100644
index 5501e9ce..00000000
--- a/docs/man/nng_log_set_level.3.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= nng_log_set_level(3)
-//
-// Copyright 2024 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_log_set_level - set minimum level for logging messagse
-
-== SYNOPSIS
-
-[source, 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);
-----
-
-== DESCRIPTION
-
-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.
-
-== SEE ALSO
-
-xref:nng_log_get_level.3.adoc[nng_log_set_level(3)]
-xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)]
diff --git a/docs/man/nng_log_set_logger.3.adoc b/docs/man/nng_log_set_logger.3.adoc
deleted file mode 100644
index eedbca49..00000000
--- a/docs/man/nng_log_set_logger.3.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-= nng_log_set_logger(3)
-//
-// Copyright 2024 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_log_set_logger - set logging handler
-
-== SYNOPSIS
-
-[source, 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
-
-The `nng_log_set_logger` 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 those may not be valid once the logger function returns.
-
-The `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 `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 `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 the `nng_stderr_log` may be used as a fallback.
-
-== SEE ALSO
-
-xref:nng_log_set_facility.3.adoc[nng_log_set_facility(3)],
-xref:nng_log_set_level.3.adoc[nng_log_set_level(3)],
-xref:nng_log.3.adoc[nng_log(3)]
diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index c5ad5f9a..094eac11 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -19,6 +19,13 @@
     - [nng_mtx](./api/thr/nng_mtx.md)
     - [nng_thread](./api/thr/nng_thread.md)
 
+  - [Logging](./api/log/index.md)
+
+    - [nng_log](./api/log/nng_log.md)
+    - [nng_log_facility](./api/log/nng_log_facility.md)
+    - [nng_log_level](./api/log/nng_log_level.md)
+    - [nng_log_logger](./api/log/nng_log_logger.md)
+
   - [Utility Functions](./api/util/index.md)
 
     - [nng_alloc](./api/util/nng_alloc.md)
diff --git a/docs/ref/api/log/nng_log.md b/docs/ref/api/log/nng_log.md
new file mode 100644
index 00000000..5d0db5a9
--- /dev/null
+++ b/docs/ref/api/log/nng_log.md
@@ -0,0 +1,75 @@
+# 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
new file mode 100644
index 00000000..28ffd05f
--- /dev/null
+++ b/docs/ref/api/log/nng_log_facility.md
@@ -0,0 +1,47 @@
+# 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
new file mode 100644
index 00000000..a875a7e0
--- /dev/null
+++ b/docs/ref/api/log/nng_log_level.md
@@ -0,0 +1,43 @@
+# 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.
+
+## 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
new file mode 100644
index 00000000..26551091
--- /dev/null
+++ b/docs/ref/api/log/nng_log_logger.md
@@ -0,0 +1,47 @@
+# 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)