[lttng-tools.git] / doc / man / Makefile.am

# SPDX-License-Identifier: GPL-2.0-only

# Man pages are only built if they are enabled at configure time.
#
# They should always be built before creating a distribution tarball.

# function which adds the source directory prefix and adds a given suffix
manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2)))

# List only the names without the .*.txt extension here:
MAN1_NAMES = \
	lttng \
	lttng-create \
	lttng-destroy \
	lttng-set-session \
	lttng-save \
	lttng-load \
	lttng-start \
	lttng-stop \
	lttng-version \
	lttng-view \
	lttng-enable-channel \
	lttng-disable-channel \
	lttng-add-context \
	lttng-list \
	lttng-track \
	lttng-untrack \
	lttng-status \
	lttng-help \
	lttng-snapshot \
	lttng-enable-event \
	lttng-disable-event \
	lttng-crash \
	lttng-metadata \
	lttng-regenerate \
	lttng-rotate \
	lttng-enable-rotation \
	lttng-disable-rotation \
	lttng-clear \
	lttng-add-trigger \
	lttng-remove-trigger \
	lttng-list-triggers
MAN3_NAMES =
MAN7_NAMES = lttng-event-rule lttng-concepts
MAN8_NAMES = lttng-sessiond lttng-relayd
MAN1_NO_ASCIIDOC_NAMES =
MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
MAN7_NO_ASCIIDOC_NAMES =
MAN8_NO_ASCIIDOC_NAMES =

# AsciiDoc sources and outputs
MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))
MAN7_TXT = $(call manaddsuffix,.7.txt,$(MAN7_NAMES))
MAN8_TXT = $(call manaddsuffix,.8.txt,$(MAN8_NAMES))
MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN7_TXT) $(MAN8_TXT)
MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT))

# common AsciiDoc source files
COMMON_TXT = \
	$(srcdir)/common-footer.txt \
	$(srcdir)/common-lttng-cmd-after-options.txt \
	$(srcdir)/common-lttng-cmd-options-head.txt \
	$(srcdir)/common-lttng-cmd-help-options.txt \
	$(srcdir)/common-help-option.txt \
	$(srcdir)/common-intro.txt \
	$(srcdir)/common-daemon-cfg.txt

# config
ASCIIDOC_CONF = $(srcdir)/asciidoc.conf
ASCIIDOC_ATTRS_CONF = $(builddir)/asciidoc-attrs.conf
XSL_FILE = $(srcdir)/manpage.xsl

# common dependencies
COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)

# man pages destinations
MAN1 = $(addsuffix .1,$(MAN1_NAMES))
MAN3 = $(addsuffix .3,$(MAN3_NAMES))
MAN7 = $(addsuffix .7,$(MAN7_NAMES))
MAN8 = $(addsuffix .8,$(MAN8_NAMES))
MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES))
MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES))
MAN7_NO_ASCIIDOC = $(addsuffix .7,$(MAN7_NO_ASCIIDOC_NAMES))
MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES))
MAN = $(MAN1) $(MAN3) $(MAN7) $(MAN8)

# initially empty
CLEANFILES =

if EMBED_HELP
mantoh_verbose = $(mantoh_verbose_@AM_V@)
mantoh_verbose_ = $(mantoh_verbose_@AM_DEFAULT_V@)
mantoh_verbose_0 = @echo "  MANTOH    " $@;

MAN1_H = $(addsuffix .1.h,$(MAN1_NAMES))
MAN3_H = $(addsuffix .3.h,$(MAN3_NAMES))
MAN8_H = $(addsuffix .8.h,$(MAN8_NAMES))
MAN_H = $(MAN1_H) $(MAN3_H) $(MAN8_H)
MAN_H_RECIPE = \
	$(mantoh_verbose_0)\
	MANWIDTH=80 @MANPROG@ --encoding=UTF-8 --no-hyphenation --no-justification --local-file $< > $@ ; \
	$(SED) -i 's/\\/\\\\/g' $@ ; \
	$(SED) -i 's/"/\\"/g' $@ ; \
	$(SED) -i 's/^\(.*\)$$/"\1\\n"/' $@

%.1.h: %.1
	$(MAN_H_RECIPE)

%.3.h: %.3
	$(MAN_H_RECIPE)

%.8.h: %.8
	$(MAN_H_RECIPE)

all-local: $(MAN_H)

CLEANFILES += $(MAN_H)
endif # EMBED_HELP

if MAN_PAGES_OPT
# at this point, we know the user asked to build the man pages
if HAVE_ASCIIDOC_XMLTO

asciidoc_verbose = $(asciidoc_verbose_@AM_V@)
asciidoc_verbose_ = $(asciidoc_verbose_@AM_DEFAULT_V@)
asciidoc_verbose_0 = @echo "  ASCIIDOC  " $@;

xmlto_verbose = $(xmlto_verbose_@AM_V@)
xmlto_verbose_ = $(xmlto_verbose_@AM_DEFAULT_V@)
xmlto_verbose_0 = @echo "  XMLTO     " $@;

# tools
ADOC = $(asciidoc_verbose)$(ASCIIDOC) -f $(ASCIIDOC_CONF) -f $(ASCIIDOC_ATTRS_CONF) -d manpage
ADOC_DOCBOOK = $(ADOC) -b docbook
XTO = $(xmlto_verbose)$(XMLTO) -m $(XSL_FILE) man

# only add this dependency if we can build the man pages because it's
# a file generated by the configure script, so it's more recent than
# the pregenerated man pages in a tarball
COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF)

# recipes
%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS)
	$(ADOC_DOCBOOK) -o $@ $<

%.1: %.1.xml $(XSL_FILE)
	$(XTO) $< 2>/dev/null

%.3.xml: $(srcdir)/%.3.txt $(COMMON_DEPS)
	$(ADOC_DOCBOOK) -o $@ $<

%.3: %.3.xml $(XSL_FILE)
	$(XTO) $< 2>/dev/null

%.7.xml: $(srcdir)/%.7.txt $(COMMON_DEPS)
	$(ADOC_DOCBOOK) -o $@ $<

%.7: %.7.xml $(XSL_FILE)
	$(XTO) $< 2>/dev/null

%.8.xml: $(srcdir)/%.8.txt $(COMMON_DEPS)
	$(ADOC_DOCBOOK) -o $@ $<

%.8: %.8.xml $(XSL_FILE)
	$(XTO) $< 2>/dev/null

# only clean the generated files if we have the tools to generate them again
CLEANFILES += $(MAN_XML) $(MAN)
else # HAVE_ASCIIDOC_XMLTO
# create man page targets used to stop the build if we want to
# build the man pages, but we don't have the necessary tools to do so
ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing."
ERR_MSG += "Make sure both tools are installed and run the configure script again."

%.1: $(srcdir)/%.1.txt $(COMMON_DEPS)
	@echo $(ERR_MSG)
	@false

%.3: $(srcdir)/%.3.txt $(COMMON_DEPS)
	@echo $(ERR_MSG)
	@false

%.7: $(srcdir)/%.7.txt $(COMMON_DEPS)
	@echo $(ERR_MSG)
	@false

%.8: $(srcdir)/%.8.txt $(COMMON_DEPS)
	@echo $(ERR_MSG)
	@false
endif # HAVE_ASCIIDOC_XMLTO
endif # MAN_PAGES_OPT

# those are always installed since they are directly written in troff
dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
dist_man3_MANS = $(MAN3_NO_ASCIIDOC)
dist_man7_MANS = $(MAN7_NO_ASCIIDOC)
dist_man8_MANS = $(MAN8_NO_ASCIIDOC)

if MAN_PAGES_OPT
# building man pages: we can install and distribute them
dist_man1_MANS += $(MAN1)
dist_man3_MANS += $(MAN3)
dist_man7_MANS += $(MAN7)
dist_man8_MANS += $(MAN8)
endif # MAN_PAGES_OPT

if !MAN_PAGES_OPT
dist-hook:
	@echo "Error: Please enable the man pages before creating a distribution tarball."
	@false
endif # !MAN_PAGES_OPT

# always distribute the source files
EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_FILE) \
	$(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in

# keep generated man pages that can be considered intermediate files
.PRECIOUS: %.1 %.3 %.7 %.8
Commit	Line	Data
	1	# SPDX-License-Identifier: GPL-2.0-only
	2
	3	# Man pages are only built if they are enabled at configure time.
	4	#
	5	# They should always be built before creating a distribution tarball.
	6
	7	# function which adds the source directory prefix and adds a given suffix
	8	manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2)))
	9
	10	# List only the names without the .*.txt extension here:
	11	MAN1_NAMES = \
	12	lttng \
	13	lttng-create \
	14	lttng-destroy \
	15	lttng-set-session \
	16	lttng-save \
	17	lttng-load \
	18	lttng-start \
	19	lttng-stop \
	20	lttng-version \
	21	lttng-view \
	22	lttng-enable-channel \
	23	lttng-disable-channel \
	24	lttng-add-context \
	25	lttng-list \
	26	lttng-track \
	27	lttng-untrack \
	28	lttng-status \
	29	lttng-help \
	30	lttng-snapshot \
	31	lttng-enable-event \
	32	lttng-disable-event \
	33	lttng-crash \
	34	lttng-metadata \
	35	lttng-regenerate \
	36	lttng-rotate \
	37	lttng-enable-rotation \
	38	lttng-disable-rotation \
	39	lttng-clear \
	40	lttng-add-trigger \
	41	lttng-remove-trigger \
	42	lttng-list-triggers
	43	MAN3_NAMES =
	44	MAN7_NAMES = lttng-event-rule lttng-concepts
	45	MAN8_NAMES = lttng-sessiond lttng-relayd
	46	MAN1_NO_ASCIIDOC_NAMES =
	47	MAN3_NO_ASCIIDOC_NAMES = lttng-health-check
	48	MAN7_NO_ASCIIDOC_NAMES =
	49	MAN8_NO_ASCIIDOC_NAMES =
	50
	51	# AsciiDoc sources and outputs
	52	MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
	53	MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))
	54	MAN7_TXT = $(call manaddsuffix,.7.txt,$(MAN7_NAMES))
	55	MAN8_TXT = $(call manaddsuffix,.8.txt,$(MAN8_NAMES))
	56	MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN7_TXT) $(MAN8_TXT)
	57	MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT))
	58
	59	# common AsciiDoc source files
	60	COMMON_TXT = \
	61	$(srcdir)/common-footer.txt \
	62	$(srcdir)/common-lttng-cmd-after-options.txt \
	63	$(srcdir)/common-lttng-cmd-options-head.txt \
	64	$(srcdir)/common-lttng-cmd-help-options.txt \
	65	$(srcdir)/common-help-option.txt \
	66	$(srcdir)/common-intro.txt \
	67	$(srcdir)/common-daemon-cfg.txt
	68
	69	# config
	70	ASCIIDOC_CONF = $(srcdir)/asciidoc.conf
	71	ASCIIDOC_ATTRS_CONF = $(builddir)/asciidoc-attrs.conf
	72	XSL_FILE = $(srcdir)/manpage.xsl
	73
	74	# common dependencies
	75	COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
	76
	77	# man pages destinations
	78	MAN1 = $(addsuffix .1,$(MAN1_NAMES))
	79	MAN3 = $(addsuffix .3,$(MAN3_NAMES))
	80	MAN7 = $(addsuffix .7,$(MAN7_NAMES))
	81	MAN8 = $(addsuffix .8,$(MAN8_NAMES))
	82	MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES))
	83	MAN3_NO_ASCIIDOC = $(addsuffix .3,$(MAN3_NO_ASCIIDOC_NAMES))
	84	MAN7_NO_ASCIIDOC = $(addsuffix .7,$(MAN7_NO_ASCIIDOC_NAMES))
	85	MAN8_NO_ASCIIDOC = $(addsuffix .8,$(MAN8_NO_ASCIIDOC_NAMES))
	86	MAN = $(MAN1) $(MAN3) $(MAN7) $(MAN8)
	87
	88	# initially empty
	89	CLEANFILES =
	90
	91	if EMBED_HELP
	92	mantoh_verbose = $(mantoh_verbose_@AM_V@)
	93	mantoh_verbose_ = $(mantoh_verbose_@AM_DEFAULT_V@)
	94	mantoh_verbose_0 = @echo " MANTOH " $@;
	95
	96	MAN1_H = $(addsuffix .1.h,$(MAN1_NAMES))
	97	MAN3_H = $(addsuffix .3.h,$(MAN3_NAMES))
	98	MAN8_H = $(addsuffix .8.h,$(MAN8_NAMES))
	99	MAN_H = $(MAN1_H) $(MAN3_H) $(MAN8_H)
	100	MAN_H_RECIPE = \
	101	$(mantoh_verbose_0)\
	102	MANWIDTH=80 @MANPROG@ --encoding=UTF-8 --no-hyphenation --no-justification --local-file $< > $@ ; \
	103	$(SED) -i 's/\\/\\\\/g' $@ ; \
	104	$(SED) -i 's/"/\\"/g' $@ ; \
	105	$(SED) -i 's/^\(.*\)$$/"\1\\n"/' $@
	106
	107	%.1.h: %.1
	108	$(MAN_H_RECIPE)
	109
	110	%.3.h: %.3
	111	$(MAN_H_RECIPE)
	112
	113	%.8.h: %.8
	114	$(MAN_H_RECIPE)
	115
	116	all-local: $(MAN_H)
	117
	118	CLEANFILES += $(MAN_H)
	119	endif # EMBED_HELP
	120
	121	if MAN_PAGES_OPT
	122	# at this point, we know the user asked to build the man pages
	123	if HAVE_ASCIIDOC_XMLTO
	124
	125	asciidoc_verbose = $(asciidoc_verbose_@AM_V@)
	126	asciidoc_verbose_ = $(asciidoc_verbose_@AM_DEFAULT_V@)
	127	asciidoc_verbose_0 = @echo " ASCIIDOC " $@;
	128
	129	xmlto_verbose = $(xmlto_verbose_@AM_V@)
	130	xmlto_verbose_ = $(xmlto_verbose_@AM_DEFAULT_V@)
	131	xmlto_verbose_0 = @echo " XMLTO " $@;
	132
	133	# tools
	134	ADOC = $(asciidoc_verbose)$(ASCIIDOC) -f $(ASCIIDOC_CONF) -f $(ASCIIDOC_ATTRS_CONF) -d manpage
	135	ADOC_DOCBOOK = $(ADOC) -b docbook
	136	XTO = $(xmlto_verbose)$(XMLTO) -m $(XSL_FILE) man
	137
	138	# only add this dependency if we can build the man pages because it's
	139	# a file generated by the configure script, so it's more recent than
	140	# the pregenerated man pages in a tarball
	141	COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF)
	142
	143	# recipes
	144	%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS)
	145	$(ADOC_DOCBOOK) -o $@ $<
	146
	147	%.1: %.1.xml $(XSL_FILE)
	148	$(XTO) $< 2>/dev/null
	149
	150	%.3.xml: $(srcdir)/%.3.txt $(COMMON_DEPS)
	151	$(ADOC_DOCBOOK) -o $@ $<
	152
	153	%.3: %.3.xml $(XSL_FILE)
	154	$(XTO) $< 2>/dev/null
	155
	156	%.7.xml: $(srcdir)/%.7.txt $(COMMON_DEPS)
	157	$(ADOC_DOCBOOK) -o $@ $<
	158
	159	%.7: %.7.xml $(XSL_FILE)
	160	$(XTO) $< 2>/dev/null
	161
	162	%.8.xml: $(srcdir)/%.8.txt $(COMMON_DEPS)
	163	$(ADOC_DOCBOOK) -o $@ $<
	164
	165	%.8: %.8.xml $(XSL_FILE)
	166	$(XTO) $< 2>/dev/null
	167
	168	# only clean the generated files if we have the tools to generate them again
	169	CLEANFILES += $(MAN_XML) $(MAN)
	170	else # HAVE_ASCIIDOC_XMLTO
	171	# create man page targets used to stop the build if we want to
	172	# build the man pages, but we don't have the necessary tools to do so
	173	ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing."
	174	ERR_MSG += "Make sure both tools are installed and run the configure script again."
	175
	176	%.1: $(srcdir)/%.1.txt $(COMMON_DEPS)
	177	@echo $(ERR_MSG)
	178	@false
	179
	180	%.3: $(srcdir)/%.3.txt $(COMMON_DEPS)
	181	@echo $(ERR_MSG)
	182	@false
	183
	184	%.7: $(srcdir)/%.7.txt $(COMMON_DEPS)
	185	@echo $(ERR_MSG)
	186	@false
	187
	188	%.8: $(srcdir)/%.8.txt $(COMMON_DEPS)
	189	@echo $(ERR_MSG)
	190	@false
	191	endif # HAVE_ASCIIDOC_XMLTO
	192	endif # MAN_PAGES_OPT
	193
	194	# those are always installed since they are directly written in troff
	195	dist_man1_MANS = $(MAN1_NO_ASCIIDOC)
	196	dist_man3_MANS = $(MAN3_NO_ASCIIDOC)
	197	dist_man7_MANS = $(MAN7_NO_ASCIIDOC)
	198	dist_man8_MANS = $(MAN8_NO_ASCIIDOC)
	199
	200	if MAN_PAGES_OPT
	201	# building man pages: we can install and distribute them
	202	dist_man1_MANS += $(MAN1)
	203	dist_man3_MANS += $(MAN3)
	204	dist_man7_MANS += $(MAN7)
	205	dist_man8_MANS += $(MAN8)
	206	endif # MAN_PAGES_OPT
	207
	208	if !MAN_PAGES_OPT
	209	dist-hook:
	210	@echo "Error: Please enable the man pages before creating a distribution tarball."
	211	@false
	212	endif # !MAN_PAGES_OPT
	213
	214	# always distribute the source files
	215	EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_FILE) \
	216	$(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in
	217
	218	# keep generated man pages that can be considered intermediate files
	219	.PRECIOUS: %.1 %.3 %.7 %.8