generate manpages with pod2man instead of a2x/asciidoc(tor)

it turned out that the upstream section in tinyproxy.conf.5 wasn't rendered
properly, because in asciidoc items following a list item are always explicitly
appended to the last list item.
after several hours of finding a workaround, it was decided to change the
manpage generator to pod2man instead.

as pod2man ships together with any perl base install, it should be available
on almost every UNIX system, unlike asciidoc which requires installation
of a huge set of dependencies (more than 1.3 GB on Ubuntu 16.04), and the
replacement asciidoctor requires a ruby installation plus a "gem" (which is
by far better than asciidoc, but still more effort than using the already
available pod2man).

tinyproxy's hard requirement of a2x (asciidoctor) for building  from source
caused rivers of tears (and dozens of support emails/issues) in the past, but
finally we get rid of it. a tool such as a2x with its XML based bloat-
technology isn't really suited to go along with a supposedly lightweight
C program.

if it ever turns out that even pod2man is too heavy a dependency, we could
still write our own replacement in less than 50 lines of awk, as the pod
syntax is very low level and easy to parse.

2 files changed, 97 insertions, 88 deletions

diff --git a/docs/man8/Makefile.am b/docs/man8/Makefile.am
index 0d1eda1..d2d7e19 100644
--- a/docs/man8/Makefile.am
+++ b/docs/man8/Makefile.am
@@ -1,35 +1,25 @@
 if HAVE_MANPAGE_INTEREST
-MAN8_FILES = \
+MAN8_FILES  = \
 	tinyproxy.txt
 endif
 
-if HAVE_XMLLINT
-A2X_ARGS = -d manpage -f manpage
-else
-A2X_ARGS = -d manpage -f manpage -L
-endif
-
-ASCIIDOCTOR_ARGS = -b manpage
+M_SECTION=8
+M_NAME=TINYPROXY
 
 man_MANS = \
 	$(MAN8_FILES:.txt=.8)
 
 .txt.8:
-if HAVE_A2X
-	$(AM_V_GEN) $(A2X) $(A2X_ARGS) $<
+if HAVE_POD2MAN
+	$(AM_V_GEN) $(POD2MAN) --center="Tinyproxy manual" \
+	--section=$(M_SECTION) --name=$(M_NAME) --release="Version @VERSION@" \
+	$< > $@
 else
-if HAVE_ASCIIDOCTOR
-	$(AM_V_GEN) $(ASCIIDOCTOR) $(ASCIIDOCTOR_ARGS) $<
-else
-	@echo "*** a2x (asciidoc) or asciidoctor is required to regenerate $(@) ***"; exit 1;
-endif
+	@echo "*** pod2man is required to regenerate $(@) ***"; exit 1;
 endif
 
 MAINTAINERCLEANFILES = \
 	$(MAN8_FILES:.txt=.8)
 
-CLEANFILES = \
-	$(MAN8_FILES:.txt=.xml)
-
-EXTRA_DIST= \
+EXTRA_DIST = \
 	$(MAN8_FILES:.txt=.8)
diff --git a/docs/man8/tinyproxy.txt.in b/docs/man8/tinyproxy.txt.in
index 54da867..a7882c1 100644
--- a/docs/man8/tinyproxy.txt.in
+++ b/docs/man8/tinyproxy.txt.in
@@ -1,24 +1,20 @@
-TINYPROXY(8)
-============
-:man source:   Version @VERSION@
-:man manual:   Tinyproxy manual
+=pod
 
-NAME
-----
+=encoding utf8
+
+=head1 NAME
 
 tinyproxy - A light-weight HTTP proxy daemon
 
 
-SYNOPSIS
---------
+=head1 SYNOPSIS
 
-*tinyproxy* [-vdch]
+B<tinyproxy> [-vdch]
 
 
-DESCRIPTION
------------
+=head1 DESCRIPTION
 
-*tinyproxy* is a light-weight HTTP proxy daemon designed to consume a
+B<tinyproxy> is a light-weight HTTP proxy daemon designed to consume a
 minimum amount of system resources. It listens on a given TCP port and
 handles HTTP proxy requests. Designed from the ground up to be fast and
 yet small, it is an ideal solution for use cases such as embedded
@@ -26,46 +22,59 @@ deployments where a full featured HTTP proxy is required, but the system
 resources for a larger proxy are unavailable.
 
 
-OPTIONS
--------
+=head1 OPTIONS
+
+B<tinyproxy> accepts the following options:
+
+=over 4
+
+=item B<-c <config-file>>
+
+Use an alternate configuration file.
+
+=item B<-d>
 
-*tinyproxy* accepts the following options:
+Don't daemonize and stay in the foreground. Useful for debugging purposes.
 
-*-c <config-file>*::
-    Use an alternate configuration file.
+=item B<-h>
 
-*-d*::
-    Don't daemonize and stay in the foreground. Useful for debugging purposes.
+Display a short help screen of command line arguments and exit.
 
-*-h*::
-    Display a short help screen of command line arguments and exit.
+=item B<-v>
 
-*-v*::
-    Display version information and exit.
+Display version information and exit.
 
+=back
 
-SIGNALS
--------
+=head1 SIGNALS
 
 In addition to command-line options, there are also several signals that
-can be sent to *tinyproxy* while it is running to generate debugging
+can be sent to B<tinyproxy> while it is running to generate debugging
 information and to force certain events.
 
-*SIGHUP*::
-    Force Tinyproxy to do a garbage collection on the current
-    connections linked list. This is usually done automatically after a
-    certain number of connections have been handled.
+=over 4
 
+=item B<SIGHUP>
 
-TEMPLATE FILES
---------------
+Force Tinyproxy to do a garbage collection on the current
+connections linked list. This is usually done automatically after a
+certain number of connections have been handled.
+
+=back
+
+=head1 TEMPLATE FILES
 
 There are two occasions when Tinyproxy delivers HTML pages to
 the client on it's own right:
 
-. When an error occurred, a corresponding error page is returned.
-. When a request for the stathost is made, a page summarizing the
-  connection statistics is returned. (See STATHOST below.)
+=over 4
+
+=item * When an error occurred, a corresponding error page is returned.
+
+=item * When a request for the stathost is made, a page summarizing the
+connection statistics is returned. (See STATHOST below.)
+
+=back
 
 The layout of both error pages and the statistics page can be
 controlled via configurable HTML template files that are plain
@@ -73,46 +82,60 @@ HTML files that additionally understand a few template
 variables.
 
 
-TEMPLATE VARIABLES
-------------------
+=head1 TEMPLATE VARIABLES
 
 There are several standard HTML variables that are available in every
 template file:
 
-*request*::
-    The full HTTP request line.
+=over 4
+
+=item B<request>
 
-*cause*::
-    The abbreviated cause of the error condition.
+The full HTTP request line.
 
-*clientip*::
-    The IP address of the client making the request.
+=item B<cause>
 
-*clienthost*::
-    The hostname of the client making the request.
+The abbreviated cause of the error condition.
 
-*version*::
-    The version of Tinyproxy.
+=item B<clientip>
 
-*package*::
-    The package name. Presently, resolves to 'tinyproxy'.
+The IP address of the client making the request.
 
-*date*::
-    The current date/time in HTTP format.
+=item B<clienthost>
+
+The hostname of the client making the request.
+
+=item B<version>
+
+The version of Tinyproxy.
+
+=item B<package>
+
+The package name. Presently, resolves to 'tinyproxy'.
+
+=item B<date>
+
+The current date/time in HTTP format.
+
+=back
 
 In addition, almost all templates support:
 
-*detail*::
-    A detailed, plain English explanation of the error and possible
-    causes.
+=over 4
+
+=item B<detail>
+
+A detailed, plain English explanation of the error and possible
+causes.
+
+=back
 
 When Tinyproxy finds a variable name enclosed in braces, e.g.
-"\{request}", then this is replaced by the value of the corresponding
+"{request}", then this is replaced by the value of the corresponding
 variable before delivery of the page.
 
 
-STATHOST
---------
+=head1 STATHOST
 
 Tinyproxy returns a HTML page with connection statistics when it
 receives a HTTP request for a certain host -- the stathost.  The
@@ -124,31 +147,27 @@ The stat file template can be changed at runtime through the
 configuration variable `StatFile`.
 
 
-FILES
------
+=head1 FILES
 
 `/etc/tinyproxy/tinyproxy.conf`, `/var/run/tinyproxy/tinyproxy.pid`, `/var/log/tinyproxy/tinyproxy.log`
 
-BUGS
-----
+=head1 BUGS
 
 To report bugs in Tinyproxy, please visit
-<https://tinyproxy.github.io/[https://tinyproxy.github.io/]>.
+L<https://tinyproxy.github.io/>.
+
 
+=head1 SEE ALSO
 
-SEE ALSO
---------
-tinyproxy.conf(5)
+L<tinyproxy.conf(5)>
 
 
-AUTHOR
-------
+=head1 AUTHOR
 
 This manpage was written by the Tinyproxy project team.
 
 
-COPYRIGHT
----------
+=head1 COPYRIGHT
 
 Copyright (c) 1998-2018 the Tinyproxy authors.