ax_prog_help2man (Autoconf Archive)

ax_prog_help2man

Synopsis

AX_PROG_HELP2MAN([program list], [man directory prefix], [binary prefix])

Description

AX_PROG_HELP2MAN is a macro designed to facilitate usage of help2man. It may take three optional arguments:

1. <program list>: comma-separated m4 list of input programs

Specifies the list of input programs which shall be used to produce man pages using help2man. If no value is specified, the macro assumes that the sole target will be named $(PACKAGE_NAME). Thus, the two following lines are equivalent:

  AX_PROG_HELP2MAN
  AX_PROG_HELP2MAN([\$(PACKAGE_NAME)])

2. <man directory prefix>: directory prefix of the man pages directory

Sets AX_HELP2MAN_PREFIX_MANS to <man directory prefix>. Defaults to ’doc/man/man1’ if no value is provided. Note that AX_HELP2MAN_PREFIX_MANS will always be a subdirectory of the build directory.

3. <binary prefix>:

Sets AX_HELP2MAN_PREFIX_BIN to <binary prefix>. Defaults to ’$(top_builddir)’ if no value is provided. The two following lines are equivalent:

  AX_PROG_HELP2MAN([subdir/program1, subdir/program2])
  AX_PROG_HELP2MAN([program1, program2], [], [\$(top_builddir)/subdir])

The macro:

- checks that help2man is available on the system.

- provides the configure option –disable-help2man.

- sets the output variable ax_help2man_MANS to the list of man pages that shall be generated.

- sets the automake conditional HAVE_HELP2MAN

- sets the substitution variable AX_HELP2MAN_RULES to the required make rules, targets and recipes.

Further detail on the macro can be found after the minimal working example. Here is a minimal working example:

  # configure.ac:
  AX_PROG_HELP2MAN

  # Makefile.am:
  if HAVE_HELP2MAN
  man1_MANS = $(ax_help2man_MANS)
  @AX_HELP2MAN_RULES@
  endif

This minimal working example shall work under the following assumptions:

1. the aforementioned binary has the same name as the project

2. the project produces a single binary at the root of the build directory

3. the man page shall be generated into the doc/man/man1 directory

Note that adding ax_help2man_MANS to man1_MANS is not needed if the man page generation is not mandatory.

The AX_HELP2MAN_RULES substitution variable shall contain:

- a recipe to create, if necessary, the destination directory.

- a generic rule to produce the manpages.

This rule targets the contents of the variable ax_help2man_MANS and its recipe shall be akin to the following:

  $(HELP2MAN) -l -N --output="$@" --name="$(shell basename $<)" "$(shell dirname $<)/$(shell basename $<)"

Errors from this rule are ignored.

- rules for each input program and target man page.

For each input program, a rule akin to the following shall be available:

  $(AX_HELP2MAN_PREFIX_MANS)/program.1: $(AX_HELP2MAN_PREFIX_BIN)/path/to/program

The macro assumes that all man pages shall be generated into the same directory (AX_HELP2MAN_PREFIX_MANS) and that all input programs can be found in the same directory (AX_HELP2MAN_PREFIX_BIN). If a subset of the inputs or outputs have different paths (for instance one of the inputs is a script available in $(top_srcdir) whereas the other inputs are programs compiled at build time), it can be customized in the Makefile.am: the target man page must be added to ax_help2man_MANS, so that it becomes a target of the generic rule for man pages and a rule must be added to specify its prerequisite:

  ax_help2man_MANS += path/to/output/man/page.1
  path/to/output/man/page.1: path/to/input/program.1

Here is a full example for a project where binaries ’program1’ and ’program2’ are compiled at build time whereas ’script’ is available in the source tree:

  # configure.ac:
    AX_PROG_HELP2MAN([program1, program2])

  # Makefile.am:
    if HAVE_HELP2MAN
    man1_MANS = $(ax_help2man_MANS)
    @AX_HELP2MAN_RULES@
    ax_help2man_MANS += $(AX_HELP2MAN_PREFIX_MANS)/script.1
    $(AX_HELP2MAN_PREFIX_MANS)/script.1: $(top_srcdir)/script
    endif

Note that this macro should not be called more than once.

Source Code

Download the latest version of ax_prog_help2man.m4 or browse the macro’s revision history.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Under Section 7 of GPL version 3, you are granted additional permissions described in the Autoconf Configure Script Exception, version 3.0, as published by the Free Software Foundation.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.