Optional manuals? Or pre-compiled in distribution?

Question

I'm working on a personal project written in C++, and I'm using GNU Autotools as build system.

I would like to distribute my software together with manual pages, but I'm not very fond of Groff. For this reason I decided to write everything in Asciidoc and to compile it in Groff with a2x.

While I'm quite satisfied with the result, I noticed that installing Asciidoc might require a lot of disk space. For instance asciidoc-base in Debian Stretch requires 1928 MB of dependencies! (Edit: not even true. I forgot to disable suggested/recommended, but the use case is relevant anyway).

One solution would be to make it optional. To achieve this my configure.ac contains the following lines:

AC_CHECK_PROG([asciidoc], [a2x], [a2x], [false])
AM_CONDITIONAL([ASCIIDOC_AVAIL], [test x$asciidoc != xfalse])

…and the man/Makefile.am file is defined as follows:

if ASCIIDOC_AVAIL

man1_MANS = foo.1
man5_MANS = foo.conf.5

foo.1: foo.1.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

foo.conf.5: foo.conf.5.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

clean:
    rm $(man1_MANS) $(man5_MANS)

endif

Even though this seems to work, I'm not very happy with it. I don't like the idea of not providing a manual.

Would it be advisable to pre-compile the man pages as part of the make dist step? In the same way as the distribution foo-x.y.z.tar.gz contains the configure script (which is not checked in the VCS but generated by autoreconf), I could make foo.1 and foo.conf.5 pre-compiled, and distributed with the source tarball.

Provided that this is acceptable from the "best practices" standpoint, how can I achieve it? I tried to declare them as EXTRA_DIST (EXTRA_DIST = man1_MANS man5_MANS) but I didn't have much luck.

Any idea?

EDIT: the Best way to add generated files to distribution? question seems to be related, even though I doubt there's a built in mechanism for my specific case.

Answer 1

even though I doubt there's a built in mechanism for my specific case.

Actually, there is such a mechanism described here, about halfway down that page. The dist_ prefix is what you are looking for:

dist_man1_MANS = foo.1
dist_man5_MANS = foo.conf.5

if ASCIIDOC_AVAIL

foo.1: foo.1.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

foo.conf.5: foo.conf.5.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

CLEANFILES += $(dist_man1_MANS) $(dist_man5_MANS)

endif

Answer 2

OP here.

Thanks to to ldav1s's answer, I came out with a good definition for my man/Makefile.am file. I put it here as an answer, but the whole credit goes to ldav1s.

Here it goes:

dist_man1_MANS = foo.1
dist_man5_MANS = foo.conf.5

EXTRA_DIST = foo.1.txt foo.conf.5.txt

if ASCIIDOC_AVAIL
foo.1: foo.1.txt
    $(asciidoc) --doctype manpage --format manpage ./$<

foo.conf.5: foo.conf.5.txt
    $(asciidoc) --doctype manpage --format manpage ./$<
endif

CLEANFILES = $(dist_man1_MANS) $(dist_man5_MANS)

Some useful information about it:

• The manpages foo.1 and foo.conf.5 are generated during make dist thanks to the dist_ prefix (as pointed out by ldav1s). The two manpages are included in the distribution tarball.

• By having the sources foo.1.txt and foo.conf.5.txt in the EXTRA_DIST I get those two files to be distributed as well. This is required, since the distribution tarball would include only the compiled manpages.

• Declaring CLEANFILES will result in make clean to delete the compiled manpages.

Just to get the idea, with this configuration I can run make dist and obtain a tarball with the following proprieties:

1. The tarball will already contain the compiled manpages together with the asciidoc sources.

2. Running ./configure && make immediately after extracting the tarball won't compile the manpages, as they are already available.

3. Running ./configure && make clean immediately after extracting the tarball will remove the compiled manpages (even if they were included in the distribution tarball);

I tried to verify the behaviour of the build system when asciidoc is installed, and when it is not installed: I get exactly what I wanted in the first place.

1. If asciidoc is not installed (thus ./configure won't detect it), running ./configure && make clean && make won't recompile the manpages

2. If asciidoc is installed, running ./configure && make clean && make will recompile the manpages.