Message ID | 20200206150645.6654-1-simon.marchi@efficios.com |
---|---|
State | Accepted, archived |
Headers | show |
Series | [lttng-ust] Fix: generation of man pages with multiple refnames | expand |
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
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[]