1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
# ===========================================================================
# https://www.gnu.org/software/autoconf-archive/ax_prog_help2man.html
# ===========================================================================
#
# 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.
#
# LICENSE
#
# Copyright (c) 2017 Harenome Ranaivoarivony-Razanajato <ranaivoarivony-razanajato@hareno.me>
#
# 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/>.
#serial 2
AC_DEFUN_ONCE([AX_PROG_HELP2MAN],
[
dnl The make rules use 'AM_V_P' and 'AM_V_at' which may not be known.
m4_pattern_allow(AM_V_P)
m4_pattern_allow(AM_V_at)
dnl Provide an option for the configure script, and check whether help2man
dnl is available and whether the user wants to use it.
AC_ARG_ENABLE(help2man,
[AS_HELP_STRING([--disable-help2man], [Disable help2man man generation])])
AC_PATH_PROG(HELP2MAN, help2man, false)
AS_IF([test "x$enable_help2man" = "xno"], [HELP2MAN="false"])
AM_CONDITIONAL([HAVE_HELP2MAN], [test "x$HELP2MAN" != "xfalse"])
dnl Default to 'doc' and $(top_builddir) if no prefixes were provided
AC_SUBST(AX_HELP2MAN_PREFIX_MANS, "\$(top_builddir)/m4_ifblank([$2], [doc/man/man1], [$2])")
AC_SUBST(AX_HELP2MAN_PREFIX_BIN, "m4_ifblank([$3], [\$(top_builddir)], [$3])")
ax_help2man_targets_text=""
m4_ifblank([$1],
dnl if no executable path was specified, default to $(PACKAGE_NAME)
[
ax_help2man_mans_list='$(AX_HELP2MAN_PREFIX_MANS)/$(PACKAGE_NAME).1'
ax_help2man_targets_text='$(AX_HELP2MAN_PREFIX_MANS)/$(PACKAGE_NAME).1: $(AX_HELP2MAN_PREFIX_BIN)/$(PACKAGE_NAME)'
],
dnl else, (if executable path(s) were specified), create rules for each target
[
m4_foreach(target, [$1],
[
ax_help2man_target="target"
ax_help2man_target_name=$(basename "${ax_help2man_target}")
ax_help2man_mans_list="${ax_help2man_mans_list} "'$(AX_HELP2MAN_PREFIX_MANS)/'"${ax_help2man_target_name}"'.1'
ax_help2man_targets_text="${ax_help2man_targets_text}
"'$(AX_HELP2MAN_PREFIX_MANS)/'"${ax_help2man_target_name}"'.1: $(AX_HELP2MAN_PREFIX_BIN)/'"${ax_help2man_target}"
])
])
dnl Reminder for $ax_help2man_rules_text:
dnl Do not insert spaces here, make rules require tabs for indentation!
dnl
dnl $(shell dirname $<)/$(shell basename $<) instead of merely $<:
dnl if the make rule prerequisite
dnl (i.e the input program for help2man) is at the root of the directory, the
dnl prerequisite text will only contain the name of the file. However,
dnl help2man needs the leading './'... Fortunately, dirname returns '.' if its
dnl input does not contain slashes!
ax_help2man_rules_text='
# Rule to create the directory for man 1 pages
$(AX_HELP2MAN_PREFIX_MANS):
$(AM_V_at)$(MKDIR_P) @S|@@
# Generic rule to create manpages using help2man
$(ax_help2man_MANS): | $(AX_HELP2MAN_PREFIX_MANS)
@if ! $(AM_V_P); then printf " %-8s %s\n" "HELP2MAN" "@S|@@"; fi
$(AM_V_at)-$(HELP2MAN) -l -N --output="@S|@@" --name="$(shell basename $<)" "$(shell dirname $<)/$(shell basename $<)"
# Targets
'"${ax_help2man_targets_text}"
AC_SUBST([ax_help2man_MANS], ["${ax_help2man_mans_list}"])
AC_SUBST([AX_HELP2MAN_RULES], ["${ax_help2man_rules_text}"])
AM_SUBST_NOTMAKE([AX_HELP2MAN_RULES])
])
|
