From 4837ffb0ad6099b9a301fc040ad0e99be681bec3 Mon Sep 17 00:00:00 2001
From: Vincent Sanders <vince@kyllikki.org>
Date: Sat, 9 Sep 2017 09:31:34 +0100
Subject: [PATCH] add some basic logging documentation

---
 docs/logging.md  | 90 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/mainpage.md |  5 +++
 2 files changed, 95 insertions(+)
 create mode 100644 docs/logging.md

diff --git a/docs/logging.md b/docs/logging.md
new file mode 100644
index 000000000..41c7ea1bd
--- /dev/null
+++ b/docs/logging.md
@@ -0,0 +1,90 @@
+NetSurf logging
+===============
+
+NetSurf has a large number of internal diagnostic messages which can
+be viewed by the developer (or user if they wish)
+
+Each message has a category and a level which can be used to control
+which messages are displayed.
+
+The message category is used to allow filters to separate messages of
+the same level from different sources.
+
+The logging levels, from low to high, are:
+
+  - DEEPDEBUG
+  - DEBUG
+  - VERBOSE
+  - INFO
+  - WARNING
+  - ERROR
+  - CRITICAL
+
+Compilation control
+-------------------
+
+At compilation time the logging behaviour can be controlled by using
+configuration overrides in a Makefile.config The parameters are:
+
+  - NETSURF_USE_NSLOG  
+  This controls if the NetSurf logging library (nslog) is used to
+  allow comprehensive filtering of messages. The value defaults to
+  AUTO which will use pkg-config to locate the library and enable if
+  present. If set to NO or the library cannot be located the browsers
+  logging will revert to simple boolean enabled/disabled logging
+  controlled by the -v command line switch.
+  
+  - NETSURF_LOG_LEVEL  
+  This controls what level of message is compiled into the NetSurf
+  binary. The default value is VERBOSE and when not using nslog this
+  value is also used to select what level of logging is shown with the
+  -v command line switch.
+  
+  - NETSURF_BUILTIN_LOG_FILTER  
+  When using nslog this sets the default non-verbose filter. The
+  default value ("level:WARNING") shows all messages of level WARNING
+  and above
+
+  - NETSURF_BUILTIN_VERBOSE_FILTER  
+  When using nslog this sets the default verbose filter. The default
+  value ("level:VERBOSE") shows all messages of level VERBOSE and
+  above. The verbose level is selected from the commandline with the
+  -v switch
+
+Command line
+------------
+
+The main command line switches that control logging are:
+
+  - -v
+  switches between the normal and verbose levels
+
+  - -V <file>
+  Send the logging to a file instead of standard output 
+  
+  - -log_filter=<filter>
+  Set the non verbose filter
+
+  - -log_verbose_filter=<filter>
+  Set the verbose filter
+
+Options
+-------
+
+The logging filters can be configured by setting the log_filter and
+log_verbose_filter options.
+
+Adding messages
+---------------
+
+Messages can be easily added by including the utils/log.h header and
+he NSLOG() macro. for example
+
+    NSLOG(netsurf, INFO, "An example message %d", example_func());
+
+nslog
+-----
+
+If the nslog library is used it allows for application of a filter to
+control which messages are output. The nslog filter syntax is best
+viewed in its [documentation](http://source.netsurf-browser.org/libnslog.git/tree/docs/mainpage.md)
diff --git a/docs/mainpage.md b/docs/mainpage.md
index 41f26d441..fa72d1464 100644
--- a/docs/mainpage.md
+++ b/docs/mainpage.md
@@ -15,6 +15,11 @@ There are some basic user guides for the
 The [core user options](docs/netsurf-options.md) of the browser are
 documented which are augmented by each frontend in a specific manner.
 
+### Logging
+
+The [logging](docs/logging.md) interface controls debug and error
+messages not output through the GUI.
+
 Documented API
 --------------