From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Tue, 5 Apr 2016 14:50:34 +0000 (-0400)
Subject: Convert man pages to AsciiDoc
X-Git-Tag: v2.9.0-rc1~149
X-Git-Url: http://git.lttng.org/?a=commitdiff_plain;h=4ddbd0b790be981d023f344a83e67a8746fa3688;hp=4ddbd0b790be981d023f344a83e67a8746fa3688;p=lttng-ust.git

Convert man pages to AsciiDoc

This patch adds a new "enable" option to the configure
script, --enable-man-pages (default) and --disable-man-pages.

When man pages are enabled, they are built and installed.

The man pages are built from their AsciiDoc sources in this way:

    AsciiDoc source -> asciidoc -> DocBook XML -> xmlto -> troff
                          ^                         ^
                       included                DocBook XSLs
                       AsciiDoc                     +
                        files                   custom XSLs

The built troff man pages should be distributed in a release
tarball. When building from a release tarball, the tools (asciidoc
and xmlto) are not strictly needed, unless a man page source is
modified/removed, in which case:

    if the tools existed at configure time:
        rebuild/update man page
    otherwise:
        show an error message which indicates why the target
        cannot be built because the tools are missing

When building from the Git repository, and when --enable-man-pages
is used, the tools are required at configure time.

The incentive for this change is to make the man pages easier to
write and maintain, AsciiDoc being far more easy to read and write
than pure troff, as well as enable rich HTML man page generation
from the intermediate DocBook XML file to publish man pages with
working internal/external links and style improvements on the
LTTng website. This also makes LTTng-UST man pages conform to the
LTTng-tools ones which use the same mechanism.

The following "redirection" man pages are also added:

  * do_tracepoint(3)
  * tracepoint(3)
  * tracepoint_enabled(3)

They all redirect to lttng-ust(3). They are always distributed,
but only installed when lttng-ust(3) is also installed (which is
when --enable-man-page exists at configure time).

See the new doc/man/README.md file for more details about the
new files and macros to use in the AsciiDoc man page source files.

This patch also contains various content fixes and updates of the
LTTng-UST man pages. Some new content is based on the online LTTng
documentation.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
---