From: Simon Marchi <simon.marchi@efficios.com>
To: lttng-dev@lists.lttng.org
Cc: Simon Marchi <simon.marchi@efficios.com>
Subject: [PATCH lttng-ust] Fix: generation of man pages with multiple refnames
Date: Thu, 6 Feb 2020 10:06:45 -0500 [thread overview]
Message-ID: <20200206150645.6654-1-simon.marchi@efficios.com> (raw)
In this proposed patch [1], we're trying to make a man page with two
command names in the NAME section, like this:
tracef, vtracef - LTTng-UST printf(3)-like interface
Doing so causes the intermediary XML (what asciidoc outputs) to contain
this:
<refnamediv>
<refname>tracef, vtracef</refname>
<refpurpose>LTTng-UST printf(3)-like interface</refpurpose>
</refnamediv>
The refname is used by the docbook XSL to determine the output
filename. This therefore results in an output file named
`tracef,_vtracef.3`, which is not desirable.
The problem is in the asciidoc pass, more specifically the part of
asciidoc.conf removed by this patch. Is is there to override the
`source`, `version` and `manual` fields, but it also inadvertently
affects the refname generation.
Instead of playing with the asciidoc output template, this patch sets
the same `source`, `version` and `manual` attributes on the asciidoc
command line. With the present patch applied, the XML output contains:
<refnamediv>
<refname>tracef</refname>
<refname>vtracef</refname>
<refpurpose>LTTng-UST printf(3)-like interface</refpurpose>
</refnamediv>
The xmlto pass (docbook XML -> man page) then generates two files,
`tracef.3` and `vtracef.3`, where `vtracef.3` simply sources `tracef.3`
(which is what we want).
[1] https://lists.lttng.org/pipermail/lttng-dev/2020-February/029524.html
Signed-off-by: Simon Marchi <simon.marchi@efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
---
doc/man/Makefile.am | 6 ++++--
doc/man/asciidoc.conf | 20 --------------------
2 files changed, 4 insertions(+), 22 deletions(-)
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index f562bfd13a66..14aa4be7c82d 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -58,8 +58,10 @@ xmlto_verbose_0 = @echo " XMLTO " $@;
# Tools to execute:
ADOC = $(asciidoc_verbose)$(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \
- -a lttng_version="$(PACKAGE_VERSION)" \
- -a lttng_ust_register_timeout="@LTTNG_UST_DEFAULT_CONSTRUCTOR_TIMEOUT_MS@"
+ -a lttng_ust_register_timeout="@LTTNG_UST_DEFAULT_CONSTRUCTOR_TIMEOUT_MS@" \
+ -a mansource="LTTng" \
+ -a manmanual="LTTng Manual" \
+ -a manversion="$(PACKAGE_VERSION)"
ADOC_DOCBOOK = $(ADOC) -b docbook
XTO = $(xmlto_verbose)$(XMLTO) -m $(XSL_FILE) man
diff --git a/doc/man/asciidoc.conf b/doc/man/asciidoc.conf
index e3c8016dc3ff..b3c8709d5ead 100644
--- a/doc/man/asciidoc.conf
+++ b/doc/man/asciidoc.conf
@@ -57,23 +57,3 @@ ifdef::backend-docbook[]
NOT
endif::backend-docbook[]
endif::doctype-manpage[]
-
-# configure XML man page header
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
-[header]
-template::[header-declarations]
-<refentry>
-<refmeta>
-<refentrytitle>{mantitle}</refentrytitle>
-<manvolnum>{manvolnum}</manvolnum>
-<refmiscinfo class="source">LTTng</refmiscinfo>
-<refmiscinfo class="version">{lttng_version}</refmiscinfo>
-<refmiscinfo class="manual">LTTng Manual</refmiscinfo>
-</refmeta>
-<refnamediv>
- <refname>{manname}</refname>
- <refpurpose>{manpurpose}</refpurpose>
-</refnamediv>
-endif::backend-docbook[]
-endif::doctype-manpage[]
--
2.25.0
next reply other threads:[~2020-02-06 15:07 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-06 15:06 Simon Marchi [this message]
2020-02-17 19:48 ` [PATCH lttng-ust] Fix: generation of man pages with multiple refnames Mathieu Desnoyers
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200206150645.6654-1-simon.marchi@efficios.com \
--to=simon.marchi@efficios.com \
--cc=lttng-dev@lists.lttng.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).