Generating man pages with asciidoc via automake

The usual way to distribute man page files with your autotools based source distribution is to write the content as .texi files, and let autotools to convert into man page format. As i more prefer asciidoc for writing documentation over texi (or any other markup language), for a autotools based project i integrated the the asciidoc to man conversion into the build configuration, using the a2x command line utility. Here is how:


0. We assume  that we already have the autotools skeleton (configure.ac. Makefile.am files), and an initial asciidoc document, placed in the 'man' subdir, populated with the usual man chapter names (NAME, USAGE, DESCRIPTION, etc, for the full list of conventional names read the man-pages man page).

 For getting started with automake see this tutorial, and to get started with writing asciidoc, check out the asciidoc user guide.


1. Add a check to configure.ac to figure out whether a2x is installed, and also export the result as automake variable:

#check for doc generating tools
AC_CHECK_PROGS([A2X], [a2x])
if test -z "$A2X";
   then AC_MSG_WARN([asciidoc a2x not found - continuing without building man pages])
fi
AM_CONDITIONAL([HAVE_A2X], [test -n "$A2X"])


2. Also add the man Makefile the list of output files in configure.ac:

AC_CONFIG_FILES([Makefile
                 man/Makefile
                 src/Makefile])

 

3. Add the man subdirectory to the top-level Makefile.am

SUBDIRS = src man

 

4. Define the additional targets in the man/Makefile.am file:

EXTRA_DIST = myproject.asciidoc

if HAVE_A2X
dir = $(top_srcdir)/man

man_MANS = myproject.1

myproject.1:
        $(A2X) -f manpage myproject.asciidoc

myproject.pdf:
        $(A2X) -f pdf myproject.asciidoc -a revdate="`date`"

CLEANFILES = myproject.1 manini.pdf

all-local: myproject.pdf manini.1
clean-local:
        rm -rf $(dir)/myproject.1
        rm -rf myproject.pdf

endif

Here we added also the source file myproject.asciidoc to the distributed tarball, and if the a2x utility is available, we add the future myproject.1 man file to manfile list, so it will installed under /share/doc/, and also define the myproject.1 target where we actually call the a2x command to do the conversion. In this case we also generate an additional PDF file from the source file, but not installing it.


5. After calling autoreconf (or autogen.sh) and ./configure in the project's root dir, you will have the Makefile.in and Makefile generated in the man subdir, and calling make will also generate the man page(s) you added.

Currently unrated