doc: Rename to babeltrace2

[babeltrace.git] / doc / man / README.adoc

= Babeltrace man pages
Philippe Proulx
4 October 2017

This directory contains the sources of the Babeltrace man pages.

The Babeltrace man pages are written in
http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
DocBook (XML) using the `asciidoc` command, and finally to troff using
the appropriate DocBook XSL stylesheet (using the `xmlto` command).


== Naming

Main program::
    +__program__.1.txt+

`babeltrace2(1)` command::
    +babeltrace2-__command__.1.txt+

Babeltrace introduction::
    `babeltrace2-intro.7.txt`

Babeltrace plugin::
    +babeltrace2-plugin-__plugin__.7.txt+

Babeltrace plugin's component class::
    +babeltrace2-__type__.__plugin__.__compcls__.7.txt+


== Macros

AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
macro definitions used everywhere in the man page sources:

+man:__page__(__section__)+::
    Use this macro to insert a link to another man page named
    +__page__+ in section +__section__+. In troff, the man page's name
    is rendered in bold.
+
Example: `man:babeltrace2-convert(1)`

+opt:__name__+::
    Use this macro to insert a link to the command-line option
    +__name__+ described in an _OPTIONS_ section in the same man page.
+
Example: `opt:--verbose`, `opt:--color='WHEN'`

+manopt:__page__(__section__):__name__+::
    Use this macro to insert a link to the command-line option
    +__name__+ described in the _OPTIONS_ section of another Babeltrace
    or LTTng man page named +__page__+ in section +__section__+.
+
Example: `manopt:babeltrace2(1):--log-level`,
+manopt:babeltrace2-convert(1):--component=\`source.ctf.fs`+

+nlopt:__name__+::
    Use this macro to write a command-line option named +__name__+
    without inserting a link. The option does not need to be described
    in the same man page.
+
Example: `nlopt:--help`

+param:__name__+::
    Use this macro to insert a link to the component initialization
    parameter named +__name__+ described in an _INITIALIZATION
    PARAMETERS_ section in the same man page.
+
Example: `param:begin`, `param:path='PATH'`

+manparam:__type__.__plug__.__compclsname__:__paramname__+::
    Use this macro to insert a link to the component initialization
    parameter +__paramname__+ described in the _INITIALIZATION
    PARAMETERS_ section of the man page of another Babeltrace component
    class. The component class has the type +__type__+, is found in the
    plugin named +__plug__+ and is named +__name__+.
+
Example: `manparam:filter.utils.trimmer:begin`,
`manparam:source.ctf.fs:path`

+nlparam:__name__+::
    Use this macro to write a component initialization parameter named
    +__name__+ without inserting a link. The parameter does not need to
    be described in the same man page.
+
Example: `nlparam:end`

+compcls:__type__.__plug__.__name__+::
    Use this macro to write a component class specification. The
    component class has the type +__type__+, is found in the plugin
    named +__plug__+ and is named +__name__+.
+
Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`

`:not:`::
    Use `:not:` to emphasize _not_.

`:escstar:`::
    Use `:escstar:` to insert `\*` literally.

`:esccomma:`::
    Use `:esccomma:` to insert `\,` literally.

`:escdot:`::
    Use `:escdot:` to insert `\.` literally.


== Attributes

`manpagetype`::
    Each man page must set this attribute to the type (lowercase) of the
    man page: `program`, `command`, `plugin`, or `component class`. It's
    used in various included files to output a text that is more
    targeted.

`revdate`::
    Each man page should have its own revision date with the following
    https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
    _28 October 1987_.
+
Make sure to update this date when you update a given man page. We are
not generating the date automatically because we want the real last
revision date in the man page, not the last build date.

Also see `asciidoc-attrs.conf` which is generated by `config.status`
from `asciidoc-attrs.conf.in`. This file contains fixed and
configuration-dependent attributes which you can use anywhere in the
sources.


== Style

Apply the recommendations of the
link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style
considerations_] section of the LTTng Documentation's contributor's
guide.