bughz/tinyproxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e81d7767d3
tinyproxy/docs/man8/Makefile.am

26 lines
454 B
Makefile
Raw Normal View History

add configure option to disable manpage generation using --disable-manpage-support it's finally possibly to disable the formerly obligatory use of a2x to generate the manpage documentation. this is the final solution to the decade old problem that users need to install the enormous asciidoc package to compile TINYproxy from source, or otherwise get a build error, even though the vast majority is only interested in the program itself. solution was inspired by PR #179. closes #179 closes #111 note that since 1.10.0 release the generated release tarball includes the generated manpages too; in which case neither the use of a2x nor --disable-manpage-support is required.
2020-08-12 07:15:45 +08:00
if HAVE_MANPAGE_INTEREST
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.
2020-08-20 05:33:59 +08:00
MAN8_FILES = \
doc: Use asciidoc for manpage
2009-09-13 06:02:38 +08:00
tinyproxy.txt
add configure option to disable manpage generation using --disable-manpage-support it's finally possibly to disable the formerly obligatory use of a2x to generate the manpage documentation. this is the final solution to the decade old problem that users need to install the enormous asciidoc package to compile TINYproxy from source, or otherwise get a build error, even though the vast majority is only interested in the program itself. solution was inspired by PR #179. closes #179 closes #111 note that since 1.10.0 release the generated release tarball includes the generated manpages too; in which case neither the use of a2x nor --disable-manpage-support is required.
2020-08-12 07:15:45 +08:00
endif
doc: Use asciidoc for manpage
2009-09-13 06:02:38 +08:00
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.
2020-08-20 05:33:59 +08:00
M_SECTION=8
M_NAME=TINYPROXY
add support for asciidoctor to generate manpages asciidoctor is a modern replacement for asciidoc and much more lightweight, issuing "apt-get install asciidoc" on ubuntu 16.04 results in an attempt to install more than 1.3 GB of dependencies.
2020-08-11 21:52:16 +08:00
doc: Use asciidoc for manpage
2009-09-13 06:02:38 +08:00
man_MANS = \
$(MAN8_FILES:.txt=.8)
.txt.8:
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.
2020-08-20 05:33:59 +08:00
if HAVE_POD2MAN
$(AM_V_GEN) $(POD2MAN) --center="Tinyproxy manual" \
--section=$(M_SECTION) --name=$(M_NAME) --release="Version @VERSION@" \
$< > $@
doc: Use asciidoc for manpage
2009-09-13 06:02:38 +08:00
else
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.
2020-08-20 05:33:59 +08:00
@echo "*** pod2man is required to regenerate $(@) ***"; exit 1;
doc: Use asciidoc for manpage
2009-09-13 06:02:38 +08:00
endif
move manpages to maintainer-clean make target according to https://www.gnu.org/prep/standards/html_node/Standard-Targets.html#Standard-Targets `maintainer-clean` is the proper make target for files that are distributed in a release tarball: > The ‘maintainer-clean’ target is intended to be used by a maintainer of the > package, not by ordinary users. > You may need special tools to reconstruct some of the files that > ‘make maintainer-clean’ deletes. this prevents users without a2x or asciidoctor from losing their ability to recompile tinyproxy after `make clean`, but it also means that users wanting to regenerate the documentation need to run `make maintainer-clean`.
2020-08-12 00:48:57 +08:00
MAINTAINERCLEANFILES = \
$(MAN8_FILES:.txt=.8)
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.
2020-08-20 05:33:59 +08:00
EXTRA_DIST = \
ship manpages as part of the dist tarball `make dist` now creates the manpages and puts them into the tarball, so the user does not need to have `a2x` installed to build them. closes #2
2016-12-21 04:07:23 +08:00
$(MAN8_FILES:.txt=.8)
Reference in New Issue Copy Permalink