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.

5 files changed, 0 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)