Search code examples
packagingautoconfautomake

Optional manuals? Or pre-compiled in distribution?

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.

Solution

  • 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