wlog: add some rudimentary documentation

docs/wlog.md

@@ -0,0 +1,145 @@
+# Overview
+
+WLog is a configurable and flexible logging system used throughout winpr and
+FreeRDP.
+
+The primary concept is to have a hierarchy of loggers that can be be configured
+independently.
+
+TODO add more details and configuration examples.
+
+
+
+# Environment variables
+
+* WLOG_APPENDER  - the appender to use
+* WLOG_PREFIX - configure the prefix used for outputting the message (see
+  Format for more details and examples)
+* WLOG_LEVEL - the level to output messages for
+* WLOG_FILTER - sets a filter for WLog messages. Only the filtered messages are
+printed
+* WLOG_FILEAPPENDER_OUTPUT_FILE_PATH  - set the output file path for the file
+file appender
+* WLOG_FILEAPPENDER_OUTPUT_FILE_NAME - set the output file name for the output
+appender
+* WLOG_JOURNALD_ID - identifier used by the journal appender
+* WLOG_UDP_TARGET - target to use for the UDP appender in the format host:port
+
+# Levels
+
+The WLog are complementary the higher level always includes the lower ones.
+The level list below is top down. Top the highest level.
+
+* WLOG_TRACE - print everything including package dumps
+* WLOG_DEBUG - debug messages
+* WLOG_INFO - general informations
+* WLOG_WARN - warnings
+* WLOG_ERROR - error
+* WLOG_FATAL - fatal problems
+* WLOG_OFF - completely disable the wlog output
+
+
+# Format
+
+The format a logger prints in has the following possible options:
+
+* "lv" - log level
+* "mn" - module name
+* "fl" - file name
+* "fn" - function
+* "ln" - line number
+* "pid" - process id
+* "tid" - thread id
+* "yr" - year
+* "mo" - month
+* "dw" - day of week
+* "hr" - hour
+* "mi" - minute
+* "se" - second
+* "ml" - milliseconds
+
+A maximum of 16 options can be used per format string.
+
+An example that generally sets the WLOG_PREFIX for xfreerdp would look like:
+```
+WLOG_PREFIX="pid=%pid:tid=%tid:fn=%fn -" xfreerdp /v:xxx
+```
+
+# Appenders
+
+WLog uses different appenders that define where the log output should be written
+to. If the application doesn't explicitly configure the appenders the above
+described variable WLOG_APPENDER can be used to choose one appender.
+
+The following represents an overview about all appenders and their possible
+configuration values.
+
+### Binary
+
+Write the log data into a binary format file.
+
+Options:
+* "outputfilename", value const char* - file to write the data to
+* "outputfilepath", value const char* - location of the output file
+
+### Callback
+The callback appender can be used from an application to get all log messages
+back the application. For example if an application wants to handle the log
+output itself.
+
+Options:
+
+* "callbacks", value struct wLogCallbacks*, callbacks to use
+
+### Console
+
+The console appender writes to the console. Depending of the operating system
+the application runs on the output might be handled differently. For example
+on android log print would be used.
+
+Options:
+
+
+* "outputstream", value const char * - output stream to write to
+  * "stdout" - write everything to stdout
+  * "stderr" - write everything to stderr
+  * "default" - use the default settings - in this case errors and fatal would
+  go to stderr everything else to stdout
+  * debug - use the debug output. Only used on windows on all operating systems
+  this behaves as as if default was set.
+
+### File
+The file appender writes the textual output to a file.
+
+Options:
+
+* "outputfilename", value const char*, filename to use
+* "outputfilepath", value const char*, location of the file
+
+### Udp
+
+This appender sends the loging messages to a pre-defined remote host via UDP.
+
+Options:
+
+* "target", value const char*, target to send the data too in the format
+host:port
+
+If no target is set the default one 127.0.0.1:20000 is used. To receive the
+log messages one can use netcat. To receive the default target the following
+command could be used.
+```
+nc -u 127.0.0.1 -p 20000 -l
+```
+
+### Syslog (optional)
+
+Use syslog for outputting the debug messages. No options available.
+
+### Journald (optional)
+
+For outputting the log messages to journald this appender can be used.
+The available options are:
+
+* "identifier", value const char*, the identifier to use for journald (default
+  is winpr)