Move to kernel style SPDX license identifiers

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

// Render with Asciidoctor

= Babeltrace{nbsp}2 manual pages
Philippe Proulx
4 September 2019
:toc:

This directory contains the sources of the Babeltrace{nbsp}2 manual
pages.

The Babeltrace{nbsp}2 manual pages are written in
https://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`

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

Babeltrace{nbsp}2 introduction::
    `babeltrace2-intro.7.txt`

Babeltrace{nbsp}2 plugin::
    `babeltrace2-plugin-__plugin-name__.7.txt`

Babeltrace{nbsp}2 component class::
    `babeltrace2-__type__.__plugin-name__.__comp-cls-name__.7.txt`

Babeltrace{nbsp}2 query object::
    `babeltrace2-query-__query-object-name__.7.txt`


== Macros

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

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

Command-line option::
+
--
`opt:__name__`::
    Insert a link to the command-line option `__name__` described in the
    _OPTIONS_ section in the same manual page.
+
Examples: `opt:--verbose`, `+opt:--color='WHEN'+`

`manopt:__page__(__section__):__name__`::
    Insert a link to the command-line option `__name__` described in the
    _OPTIONS_ section of another Babeltrace{nbsp}2 or LTTng manual page
    named `__page__` in section `__section__`.
+
Examples: `manopt:babeltrace2(1):--log-level`,
`+manopt:babeltrace2-convert(1):--component=pass:[`source.ctf.fs`]+`

`nlopt:__name__`::
    Write a command-line option named `__name__` without inserting a
    link. The option does not need to be described in the same manual
    page.
+
Examples: `nlopt:--help`, `+nlopt:--log-level='LEVEL'+`
--

Component initialization or query parameter::
+
--
`param:__name__`::
    Insert a link to the component initialization or query parameter
    named `__name__` described in an _INITIALIZATION PARAMETERS_ or
    _PARAMETERS_ section in the same manual page.
+
Examples: `param:begin`, `+param:inputs='PATHS'+`

`manparam:__type__.__plugin-name__.__comp-cls-name__:__param-name__`::
    Insert a link to the component initialization or query parameter
    `__param-name__` described in the _INITIALIZATION PARAMETERS_ or
    _PARAMETERS_ section of the manual page of another Babeltrace{nbsp}2
    component class. The component class has the type `__type__`, is
    found in the plugin named `__plugin-name__`, and is named
    `__comp-cls-name__`.
+
Examples: `manparam:filter.utils.trimmer:begin`,
`manparam:source.ctf.fs:inputs`

`nlparam:__name__`::
    Write a component initialization or query parameter named `__name__`
    without inserting a link. The parameter does not need to be
    described in the same manual page.
+
Example: `nlparam:end`

`qres:__name__`::
    Insert a link to the query result object entry named `__name__`
    described in a _RESULT OBJECT_ section in the same manual page.
+
Examples: `qres:input`, `+qres:group='GROUP'+`

`nlqres:__name__`::
    Write a query result object entry named `__name__` without inserting
    a link. The entry does not need to be described in the same manual
    page.
+
Example: `nlqres:group`

`vtype:[__type__]`::
    Write a value object type `__type__`.
+
Examples: `vtype:[optional boolean]`, `vtype:[signed integer or string]`
--

Component class::
+
--
`compcls:__type__.__plugin-name__.__comp-cls-name__`::
    Write a component class specification. The component class has the
    type `__type__`, is found in the plugin named `__plugin-name__`, and
    is named `__comp-cls-name__`.
+
Examples: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
--

Text emphasis and replacement::
+
--
`:all:`::
    Emphasize "`all`".

`:not:`::
    Emphasize "`not`".

`:escstar:`::
    Insert `+\*+` literally.

`:esccomma:`::
    Insert `+\,+` literally.

`:escdot:`::
    Insert `+\.+` literally.
--


== Attributes

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

`revdate`::
    Each manual page must 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 manual page. We
are not generating the date automatically because we want the real last
revision date in the manual 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.


== Internal links

Internal links have no special formatting once converted to troff: it
would look weird as there's no navigation in troff. We use them for
cross-references since the manual page sources are also used to generate
parts of the Babeltrace{nbsp}2 website.

When an internal link's text is the name of a section (usually following
"`see`"), put the section name between `pass:[``]` and `+''+` to outline
it:

----
Lorem ipsum dolor sit amet (see <<sect-id,``The section name''>>),
consectetur adipiscing elit.
----

This makes the manual page result look like this:

----
       Lorem ipsum dolor sit amet (see “The section name”), consectetur
       adipiscing elit.
----


== 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.