* [PATCH lttng-ust] Fix: generation of man pages with multiple refnames
@ 2020-02-06 15:06 Simon Marchi
2020-02-17 19:48 ` Mathieu Desnoyers
0 siblings, 1 reply; 2+ messages in thread
From: Simon Marchi @ 2020-02-06 15:06 UTC (permalink / raw)
To: lttng-dev; +Cc: Simon Marchi
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
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH lttng-ust] Fix: generation of man pages with multiple refnames
2020-02-06 15:06 [PATCH lttng-ust] Fix: generation of man pages with multiple refnames Simon Marchi
@ 2020-02-17 19:48 ` Mathieu Desnoyers
0 siblings, 0 replies; 2+ messages in thread
From: Mathieu Desnoyers @ 2020-02-17 19:48 UTC (permalink / raw)
To: Simon Marchi; +Cc: lttng-dev
Merged into lttng-ust master branch, thanks!
Mathieu
----- On Feb 6, 2020, at 10:06 AM, Simon Marchi simon.marchi@efficios.com wrote:
> 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
>
> _______________________________________________
> lttng-dev mailing list
> lttng-dev@lists.lttng.org
> https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
--
Mathieu Desnoyers
EfficiOS Inc.
http://www.efficios.com
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-02-17 19:48 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-06 15:06 [PATCH lttng-ust] Fix: generation of man pages with multiple refnames Simon Marchi
2020-02-17 19:48 ` Mathieu Desnoyers
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).