Convert the manual page from roff to rst.

The advantage of ReStructuredText is that this allows converting the
same source into different formats, such as HTML.

Signed-off-by: Gergely Nagy <algernon@balabit.hu>

3 files changed, 139 insertions, 213 deletions

diff --git a/lib/Makefile.am b/lib/Makefile.am
index a208bc2..030ae4e 100644
--- a/lib/Makefile.am
+++ b/lib/Makefile.am
@@ -14,5 +14,3 @@ libumberlog_include_HEADERS	= umberlog.h
 
 pkgconfigdir			= $(libdir)/pkgconfig
 pkgconfig_DATA			= libumberlog.pc
-
-man3_MANS			= umberlog.3
diff --git a/lib/umberlog.3 b/lib/umberlog.3
deleted file mode 100644
index ee7be30..0000000
--- a/lib/umberlog.3
+++ /dev/null
@@ -1,211 +0,0 @@
-.\" umberlog.3 -- CEE-enhanced syslog manual
-.\"
-.\" Copyright (c) 2012 BalaBit IT Security Ltd.
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY BALABIT AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL BALABIT OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.TH UMBERLOG 3 2012-03-22 "libumberlog" "CEE\-enhanced syslog Manual"
-
-.SH NAME
-ul_openlog, ul_syslog, ul_vsyslog, ul_legacy_syslog,
-ul_legacy_vsyslog \- send CEE-enhanced messages to the system logger
-.br
-ul_format, ul_vformat \- format CEE\-enhanced messages, without
-sending them to the system logger
-
-.SH SYNOPSIS
-.B #include <umberlog.h>
-.sp
-.BI "void ul_openlog(const char *" ident ", int " option ", int " facility );
-.br
-
-.br
-.BI "void ul_syslog(int " priority ", const char *" format ", ...);"
-.br
-.BI "void ul_vsyslog(int " priority ", const char *" format ", va_list " ap );
-.br
-
-.br
-.BI "void ul_legacy_syslog(int " priority ", const char *" format ", ...);"
-.br
-.BI "void ul_legacy_vsyslog(int " priority ", const char *" format ", va_list " ap );
-.br
-
-.br
-.BI "char *ul_format(int " priority ", const char *" format ", ...);"
-.br
-.BI "char *ul_vformat(int " priority ", const char *" format ", va_list " ap );
-
-.SH DESCRIPTION
-.BR ul_openlog (),
-(also aliased to
-.BR openlog ())
-is a wrapper around the original
-.BR openlog ()
-function, which opens a connection to the system logger for a
-program. The updated version adds support for a number of new option
-flags, described below.
-
-.sp
-.BR ul_legacy_syslog ()
-and
-.BR ul_legacy_vsyslog ()
-are both thin layers over the original
-.BR syslog ()
-and
-.BR vsyslog ()
-functions, and the library overrides the original functions with this
-two. The only change these functions bring, are that the message they
-generate will be a CEE\-enhanced message, with a JSON payload. See
-below for an explanation on what this means.
-
-.sp
-.BR ul_syslog ()
-and
-.BR ul_vsyslog ()
-are two new functions provided by the library, that have similar
-interface to the legacy
-.BR syslog ()
-functions, but they can be used to add arbitrary key-value pairs to
-the emitted message. After the
-.I msg_format
-format string, and any other parameters it refers to, there must be a
-NULL-terminated list of
-.IR key ", " "value format" ", " "format parameters" .
-Each of these pairs, constructed from the
-.I key
-and the
-.BR printf (3)-style
-.I value format
-will be added to the generated message.
-
-.sp
-.BR ul_format ()
-and
-.BR ul_vformat ()
-do the same as the syslog variants above, except the formatted payload
-is not sent to syslog, but returned as a newly allocated string.
-
-.SH "CEE PAYLOAD"
-
-All of the improved
-.BR syslog ()
-functions, the legacy and overridden ones and the new ones too turn
-the original syslog message into a CEE\-enabled JSON payload, with the
-original message put into the
-.I msg
-field, and any additional fields put into the same structure.
-
-By default, unless the
-.B LOG_UL_NODISCOVER
-option flag is set, all of these functions will also add a few
-automatically discovered fields into the payload:
-
-.TP 15
-.I pid
-The process ID of the program, as returned by
-.BR getpid ().
-The value of this is \- by default \- determined at the time of
-calling
-.BR ul_openlog (),
-but if caching is disabled, it will be rechecked every time.
-.TP
-.IR facility " and " priority
-The syslog facility and priority as a text string.
-.TP
-.I program
-The identification set at the time of
-.BR ul_openlog ().
-.TP
-.IR uid " and " gid
-The user and group ID of the process, determined at
-.BR ul_openlog ()
-time by default, unless caching is disabled.
-.TP
-.I host
-The name of the originating host, determined at
-.BR ul_openlog ()
-time by default, using
-.BR gethostname ().
-.TP
-.I timestamp
-High\-precision timestamp, in textual format. Included by default, but
-can be controlled by the
-.B LOG_UL_NOTIME
-option flag at
-.BR ul_openlog ()
-time.
-.PP
-
-.SH "EXTRA OPTION FLAGS"
-The
-.I option
-argument to
-.BR ul_openlog ()
-is an OR of any of the original
-.BR openlog ()
-flags, and these:
-.TP 15
-.B LOG_UL_NODISCOVER
-Disable all automatic\-discovery, and only include the
-.I message
-and any specified
-.I key\-value
-pairs in the generated message.
-.TP
-.B LOG_UL_NOCACHE
-When automatic discovery is enabled, disable caching certain
-properties, that might change between the call to
-.BR openlog ()
-and the
-.BR ul_syslog ()
-invocation.
-.TP
-.B LOG_UL_NOCACHE_UID
-Disable caching the
-.IR uid " and " gid
-caching when automatic discovery is enabled, but do cache the rest.
-.TP
-.B LOG_UL_NOTIME
-Do not add a high\-precision timestamp to the generated message when
-automatic discovery is enabled.
-.PP
-
-.SH EXAMPLES
-.nf
-
-    ul_syslog(LOG_NOTICE, "Logged in user: %s", username,
-              "service", "%s", service,
-              "auth-method", "%s", auth_method,
-              "sessionid", "%d", session_id,
-              NULL);
-.fi
-
-.SH "SEE ALSO"
-.BR syslog (1)
-
-.SH COLOPHON
-This page is part of the
-.I libumberlog
-project, and is available under the same 2-clause BSD license as the
-rest of the project.
diff --git a/lib/umberlog.rst b/lib/umberlog.rst
new file mode 100644
index 0000000..036341b
--- /dev/null
+++ b/lib/umberlog.rst
@@ -0,0 +1,139 @@
+========
+umberlog
+========
+
+--------------------------------------
+CEE-enhanced syslog message generation
+--------------------------------------
+
+:Author: Gergely Nagy <algernon@balabit.hu>
+:Date: 2012-03-23
+:Manual section: 1
+:Manual group: CEE-enhanced syslog Manual
+
+SYNOPSIS
+========
+
+::
+   
+   #include <umberlog.h>
+
+   void ul_openlog (const char *ident, int option, int facility);
+
+   void ul_syslog (int priority, const char *format, ....);
+   void ul_vsyslog (int priority, const char *format, va_list ap);
+
+   void ul_legacy_syslog (int priority, const char *format, ...);
+   void ul_legacy_vsyslog (int priority, const char *format, va_list ap);
+
+   void ul_format (int priority, const char *format, ...);
+   void ul_vformat (int priority, const char *format, va_list ap);
+
+DESCRIPTION
+===========
+
+**ul_openlog()** (also aliased to **openlog()**) is a wrapper around
+the original **openlog()** function, which opens a connection to the
+system logger for a program. The updated version adds support for a
+number of new option flags, described below.
+
+**ul_legacy_syslog()** and **ul_legacy_vsyslog()** are both thin
+layers over the original **syslog()** and **vsyslog()** functions, and
+the library overrides the original functions with this two. The only
+change these functions bring, are that the message they generate will
+be a CEE-enhanced message, with a JSON payload. See below for an
+explanation on what this means.
+
+_syslog()** and **ul_vsyslog()** are two new functions provided by the
+library, that have similar interface to the legacy **syslog()**
+functions, but they can be used to add arbitrary key-value pairs to
+the emitted message. After the *msg_format* format string, and any
+other parameters it refers to, there must be a NULL-terminated list of
+*key*, *value format*, *format parameters*. Each of these pairs,
+constructed from the *key* and the **printf(3)**-style *value format*
+will be added to the generated message.
+
+**ul_format()** and **ul_vformat()** do the same as the syslog
+variants above, except the formatted payload is not sent to syslog,
+but returned as a newly allocated string.
+
+CEE PAYLOAD
+===========
+
+All of the improved **syslog()** functions, the legacy and overridden
+ones and the new ones too turn the original syslog message into a
+CEE-enabled JSON payload, with the original message put into the *msg*
+field, and any additional fields put into the same structure.
+
+By default, unless the **LOG_UL_NODISCOVER** option flag is set, all
+of these functions will also add a few automatically discovered fields
+into the payload:
+
+*pid*
+  The process ID of the program, as returned by **getpid()** The value
+  of this is - by default - determined at the time of calling
+  **ul_openlog()**, but if caching is disabled, it will be rechecked
+  every time.
+
+*facility*, *priority*
+  The syslog facility and priority as a text string.
+
+*program*
+  The identification set at the time of **ul_openlog()**.
+
+*uid*, *gid*
+  The user and group ID of the process, determined at **ul_openlog()**
+  time by default, unless caching is disabled.
+
+*host*
+  The name of the originating host, determined at **ul_openlog()**
+  time by default, using **gethostname()**.
+
+*timestamp*
+  High-precision timestamp, in textual format. Included by default,
+  but can be controlled by the **LOG_UL_NOTIME** option flag at
+  **ul_openlog()** time.
+
+EXTRA OPTION FLAGS
+==================
+
+The *option* argument to **ul_openlog()** is an OR of any of the
+original **openlog()** flags, and these:
+
+LOG_UL_NODISCOVER
+  Disable all automatic discovery, and only include the *message*,
+  and any specified *key-value* pairs in the generated message.
+
+LOG_UL_NOCACHE
+  When automatic discovery is enabled, disable caching certain
+  properties, that might change between the call to **openlog()** and
+  the **ul_syslog()** invocation.
+
+LOG_UL_NOCACHE_UID
+  Disable the *uid* and *gid* caching when automatic discovery is
+  enabled, but do cache the rest.
+  
+LOG_UL_NOTIME
+  Do not add a high-precision timestamp to the generated message when
+  automatic discovery is enabled.
+
+EXAMPLES
+========
+
+::
+
+    ul_syslog(LOG_NOTICE, "Logged in user: %s", username,
+              "service", "%s", service,
+              "auth-method", "%s", auth_method,
+              "sessionid", "%d", session_id,
+              NULL);
+
+SEE ALSO
+========
+**syslog(1)**
+
+COPYRIGHT
+=========
+
+This page is part of the *libumberlog* project, and is available under
+the same 2-clause BSD license as the rest of the project.