doc/man: convert openvpn.8 to split-up .rst files

To avoid keeping around a full-size openvpn.rst file which is never
needed but will take space in the repo forever, patches 01...04
of the big documentation overhaul projects were squashed togehter,
keeping the individual commit logs and URL references below.

Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is a combination of 4 commits.
* This is the 1st commit message:

doc/man: Add an .rst formatted version of the man page

This is the first step to move away from a manually editing g/nroff
encoded man page.

Some modifications was needed to ensure formatting was consistent and
rendered reasonably okay in GitHub and that the generated man page
(using rst2man) is looking as a proper man page.  Unsupported options
has also been moved into its own section.  HTML rendering directly
using rst2html has also been used to validate the conversion.

The rst2man and rst2html utilities comes from the python-docutils
project: https://docutils.sourceforge.io/

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-2-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063370/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is the commit message #2:

doc/man: Replace old man page with generated man page

The doc/openvpn.8 and doc/openvpn.8.html files are now being removed
from the git tree, as it will be generated from the doc/openvpn.8.rst
file using python-docutils.

An additional dist-hook is added so these files are generated
automatically when source tarballs are generated for releases.  This
means users compiling directly from the source tarball will not need
python-docutils installed.

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-3-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063373/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is the commit message #3:

doc/man: Split up and reorganize main man page

The openvpn.8.rst file is quite long and hard to edit, as it covers
several hundred options.  Some options were even documented multiple
places.  The example has also received some attention, cleaning up
old and outdated infomration.

In this commit the main man page is split up into multiple sections
and options are sorted into each of the corresponding section.
Inside each category, each option is for now sorted alphabetically.
The main openvpn.8.rst file is currently kept unchanged and will be
handled in the next commit.

Many language improvements contributed by Richard Bonhomme has also
been incorproated.

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-4-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063376/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is the commit message #4:

doc/man: Complete openvpn.8.rst splitting

This rebuilds the openvpn.8.rst content by using the text which was
split out in the previous commit by using RST ..include statements.

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-5-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063377/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/man-sections/signals.rst b/doc/man-sections/signals.rst
new file mode 100644
index 0000000..63611b3
--- /dev/null
+++ b/doc/man-sections/signals.rst
@@ -0,0 +1,30 @@
+SIGNALS
+=======
+
+:code:`SIGHUP`
+    Cause OpenVPN to close all TUN/TAP and network connections, restart,
+    re-read the configuration file (if any), and reopen TUN/TAP and network
+    connections.
+
+:code:`SIGUSR1`
+    Like :code:`SIGHUP``, except don't re-read configuration file, and
+    possibly don't close and reopen TUN/TAP device, re-read key files,
+    preserve local IP address/port, or preserve most recently authenticated
+    remote IP address/port based on ``--persist-tun``, ``--persist-key``,
+    ``--persist-local-ip`` and ``--persist-remote-ip`` options respectively
+    (see above).
+
+    This signal may also be internally generated by a timeout condition,
+    governed by the ``--ping-restart`` option.
+
+    This signal, when combined with ``--persist-remote-ip``, may be sent
+    when the underlying parameters of the host's network interface change
+    such as when the host is a DHCP client and is assigned a new IP address.
+    See ``--ipchange`` for more information.
+
+:code:`SIGUSR2`
+    Causes OpenVPN to display its current statistics (to the syslog file if
+    ``--daemon`` is used, or stdout otherwise).
+
+:code:`SIGINT`, :code:`SIGTERM`
+    Causes OpenVPN to exit gracefully.