1@node ax_prog_help2man 2@unnumberedsec ax_prog_help2man 3 4@majorheading Synopsis 5 6@smallexample 7AX_PROG_HELP2MAN([program list], [man directory prefix], [binary prefix]) 8@end smallexample 9 10@majorheading Description 11 12AX_PROG_HELP2MAN is a macro designed to facilitate usage of help2man. It 13may take three optional arguments: 14 151. <program list>: comma-separated m4 list of input programs 16 17Specifies the list of input programs which shall be used to produce man 18pages using help2man. If no value is specified, the macro assumes that 19the sole target will be named $(PACKAGE_NAME). Thus, the two following 20lines are equivalent: 21 22@smallexample 23 AX_PROG_HELP2MAN 24 AX_PROG_HELP2MAN([\$(PACKAGE_NAME)]) 25@end smallexample 26 272. <man directory prefix>: directory prefix of the man pages directory 28 29Sets AX_HELP2MAN_PREFIX_MANS to <man directory prefix>. Defaults to 30'doc/man/man1' if no value is provided. Note that 31AX_HELP2MAN_PREFIX_MANS will always be a subdirectory of the build 32directory. 33 343. <binary prefix>: 35 36Sets AX_HELP2MAN_PREFIX_BIN to <binary prefix>. Defaults to 37'$(top_builddir)' if no value is provided. The two following lines are 38equivalent: 39 40@smallexample 41 AX_PROG_HELP2MAN([subdir/program1, subdir/program2]) 42 AX_PROG_HELP2MAN([program1, program2], [], [\$(top_builddir)/subdir]) 43@end smallexample 44 45The macro: 46 47- checks that help2man is available on the system. 48 49- provides the configure option --disable-help2man. 50 51- sets the output variable ax_help2man_MANS to the list of man pages 52that shall be generated. 53 54- sets the automake conditional HAVE_HELP2MAN 55 56- sets the substitution variable AX_HELP2MAN_RULES to the required make 57rules, targets and recipes. 58 59Further detail on the macro can be found after the minimal working 60example. Here is a minimal working example: 61 62@smallexample 63 # configure.ac: 64 AX_PROG_HELP2MAN 65@end smallexample 66 67@smallexample 68 # Makefile.am: 69 if HAVE_HELP2MAN 70 man1_MANS = $(ax_help2man_MANS) 71 @@AX_HELP2MAN_RULES@@ 72 endif 73@end smallexample 74 75This minimal working example shall work under the following assumptions: 76 771. the aforementioned binary has the same name as the project 78 792. the project produces a single binary at the root of the build 80directory 81 823. the man page shall be generated into the doc/man/man1 directory 83 84Note that adding ax_help2man_MANS to man1_MANS is not needed if the man 85page generation is not mandatory. 86 87The AX_HELP2MAN_RULES substitution variable shall contain: 88 89- a recipe to create, if necessary, the destination directory. 90 91- a generic rule to produce the manpages. 92 93This rule targets the contents of the variable ax_help2man_MANS and its 94recipe shall be akin to the following: 95 96@smallexample 97 $(HELP2MAN) -l -N --output="$@@" --name="$(shell basename $<)" "$(shell dirname $<)/$(shell basename $<)" 98@end smallexample 99 100Errors from this rule are ignored. 101 102- rules for each input program and target man page. 103 104For each input program, a rule akin to the following shall be available: 105 106@smallexample 107 $(AX_HELP2MAN_PREFIX_MANS)/program.1: $(AX_HELP2MAN_PREFIX_BIN)/path/to/program 108@end smallexample 109 110The macro assumes that all man pages shall be generated into the same 111directory (AX_HELP2MAN_PREFIX_MANS) and that all input programs can be 112found in the same directory (AX_HELP2MAN_PREFIX_BIN). If a subset of the 113inputs or outputs have different paths (for instance one of the inputs 114is a script available in $(top_srcdir) whereas the other inputs are 115programs compiled at build time), it can be customized in the 116Makefile.am: the target man page must be added to ax_help2man_MANS, so 117that it becomes a target of the generic rule for man pages and a rule 118must be added to specify its prerequisite: 119 120@smallexample 121 ax_help2man_MANS += path/to/output/man/page.1 122 path/to/output/man/page.1: path/to/input/program.1 123@end smallexample 124 125Here is a full example for a project where binaries 'program1' and 126'program2' are compiled at build time whereas 'script' is available in 127the source tree: 128 129@smallexample 130 # configure.ac: 131 AX_PROG_HELP2MAN([program1, program2]) 132@end smallexample 133 134@smallexample 135 # Makefile.am: 136 if HAVE_HELP2MAN 137 man1_MANS = $(ax_help2man_MANS) 138 @@AX_HELP2MAN_RULES@@ 139 ax_help2man_MANS += $(AX_HELP2MAN_PREFIX_MANS)/script.1 140 $(AX_HELP2MAN_PREFIX_MANS)/script.1: $(top_srcdir)/script 141 endif 142@end smallexample 143 144Note that this macro should not be called more than once. 145 146@majorheading Source Code 147 148Download the 149@uref{http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=blob_plain;f=m4/ax_prog_help2man.m4,latest 150version of @file{ax_prog_help2man.m4}} or browse 151@uref{http://git.savannah.gnu.org/gitweb/?p=autoconf-archive.git;a=history;f=m4/ax_prog_help2man.m4,the 152macro's revision history}. 153 154@majorheading License 155 156@w{Copyright @copyright{} 2017 Harenome Ranaivoarivony-Razanajato @email{ranaivoarivony-razanajato@@hareno.me}} 157 158This program is free software; you can redistribute it and/or modify it 159under the terms of the GNU General Public License as published by the 160Free Software Foundation; either version 3 of the License, or (at your 161option) any later version. 162 163This program is distributed in the hope that it will be useful, but 164WITHOUT ANY WARRANTY; without even the implied warranty of 165MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 166Public License for more details. 167 168Under Section 7 of GPL version 3, you are granted additional permissions 169described in the Autoconf Configure Script Exception, version 3.0, as 170published by the Free Software Foundation. 171 172You should have received a copy of the GNU General Public License along 173with this program. If not, see <https://www.gnu.org/licenses/>. 174