[lttng-ust] Fix: generation of man pages with multiple refnames

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 at efficios.com>
Signed-off-by: Philippe Proulx <eeppeliteloop at gmail.com>
---
 doc/man/Makefile.am   |  6 ++++--
 doc/man/asciidoc.conf | 20 --------------------
 2 files changed, 4 insertions(+), 22 deletions(-)

Merged into lttng-ust master branch, thanks!

Mathieu

----- On Feb 6, 2020, at 10:06 AM, Simon Marchi simon.marchi at 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 at efficios.com>
> Signed-off-by: Philippe Proulx <eeppeliteloop at 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 at lists.lttng.org
> https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev