From a547a298c77c331061511a6befffc346c1a44a05 Mon Sep 17 00:00:00 2001 From: rofl0r Date: Wed, 19 Aug 2020 22:33:59 +0100 Subject: 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. --- docs/man5/Makefile.am | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) (limited to 'docs/man5/Makefile.am') diff --git a/docs/man5/Makefile.am b/docs/man5/Makefile.am index 3447ad2..31b8ddf 100644 --- a/docs/man5/Makefile.am +++ b/docs/man5/Makefile.am @@ -3,33 +3,23 @@ MAN5_FILES = \ tinyproxy.conf.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=5 +M_NAME=TINYPROXY.CONF man_MANS = \ $(MAN5_FILES:.txt=.5) .txt.5: -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 = \ $(MAN5_FILES:.txt=.5) -CLEANFILES = \ - $(MAN5_FILES:.txt=.xml) - EXTRA_DIST = \ $(MAN5_FILES:.txt=.5) -- cgit v1.2.3