1 // Render with Asciidoctor
3 = Babeltrace{nbsp}2 manual pages
8 This directory contains the sources of the Babeltrace{nbsp}2 manual
11 The Babeltrace{nbsp}2 manual pages are written in
12 https://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
13 DocBook (XML) using the `asciidoc` command, and finally to troff using
14 the appropriate DocBook XSL stylesheet (using the `xmlto` command).
22 Specific `babeltrace2(1)` command::
23 `babeltrace2-__command__.1.txt`
25 Babeltrace{nbsp}2 introduction::
26 `babeltrace2-intro.7.txt`
28 Babeltrace{nbsp}2 plugin::
29 `babeltrace2-plugin-__plugin-name__.7.txt`
31 Babeltrace{nbsp}2 component class::
32 `babeltrace2-__type__.__plugin-name__.__comp-cls-name__.7.txt`
34 Babeltrace{nbsp}2 query object::
35 `babeltrace2-query-__query-object-name__.7.txt`
40 AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
41 macro definitions used everywhere in the manual page sources:
46 `man:__page__(__section__)`::
47 Insert a link to another manual page named `__page__` in section
48 `__section__`. In troff, the manual page's name is rendered in bold.
50 Example: `man:babeltrace2-convert(1)`
57 Insert a link to the command-line option `__name__` described in the
58 _OPTIONS_ section in the same manual page.
60 Examples: `opt:--verbose`, `+opt:--color='WHEN'+`
62 `manopt:__page__(__section__):__name__`::
63 Insert a link to the command-line option `__name__` described in the
64 _OPTIONS_ section of another Babeltrace{nbsp}2 or LTTng manual page
65 named `__page__` in section `__section__`.
67 Examples: `manopt:babeltrace2(1):--log-level`,
68 `+manopt:babeltrace2-convert(1):--component=pass:[`source.ctf.fs`]+`
71 Write a command-line option named `__name__` without inserting a
72 link. The option does not need to be described in the same manual
75 Examples: `nlopt:--help`, `+nlopt:--log-level='LEVEL'+`
78 Component initialization or query parameter::
82 Insert a link to the component initialization or query parameter
83 named `__name__` described in an _INITIALIZATION PARAMETERS_ or
84 _PARAMETERS_ section in the same manual page.
86 Examples: `param:begin`, `+param:inputs='PATHS'+`
88 `manparam:__type__.__plugin-name__.__comp-cls-name__:__param-name__`::
89 Insert a link to the component initialization or query parameter
90 `__param-name__` described in the _INITIALIZATION PARAMETERS_ or
91 _PARAMETERS_ section of the manual page of another Babeltrace{nbsp}2
92 component class. The component class has the type `__type__`, is
93 found in the plugin named `__plugin-name__`, and is named
96 Examples: `manparam:filter.utils.trimmer:begin`,
97 `manparam:source.ctf.fs:inputs`
100 Write a component initialization or query parameter named `__name__`
101 without inserting a link. The parameter does not need to be
102 described in the same manual page.
104 Example: `nlparam:end`
107 Insert a link to the query result object entry named `__name__`
108 described in a _RESULT OBJECT_ section in the same manual page.
110 Examples: `qres:input`, `+qres:group='GROUP'+`
113 Write a query result object entry named `__name__` without inserting
114 a link. The entry does not need to be described in the same manual
117 Example: `nlqres:group`
120 Write a value object type `__type__`.
122 Examples: `vtype:[optional boolean]`, `vtype:[signed integer or string]`
128 `compcls:__type__.__plugin-name__.__comp-cls-name__`::
129 Write a component class specification. The component class has the
130 type `__type__`, is found in the plugin named `__plugin-name__`, and
131 is named `__comp-cls-name__`.
133 Examples: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
136 Text emphasis and replacement::
146 Insert `+\*+` literally.
149 Insert `+\,+` literally.
152 Insert `+\.+` literally.
159 Each manual page must set this attribute to the type (lowercase) of
160 the manual page: `program`, `command`, `plugin`, or `component
161 class`. It's used in various included files to output a text that is
165 Each manual page must have its own revision date with the following
166 https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
169 Make sure to update this date when you update a given manual page. We
170 are not generating the date automatically because we want the real last
171 revision date in the manual page, not the last build date.
173 Also see `asciidoc-attrs.conf` which is generated by `config.status`
174 from `asciidoc-attrs.conf.in`. This file contains fixed and
175 configuration-dependent attributes which you can use anywhere in the
181 Internal links have no special formatting once converted to troff: it
182 would look weird as there's no navigation in troff. We use them for
183 cross-references since the manual page sources are also used to generate
184 parts of the Babeltrace{nbsp}2 website.
186 When an internal link's text is the name of a section (usually following
187 "`see`"), put the section name between `pass:[``]` and `+''+` to outline
191 Lorem ipsum dolor sit amet (see <<sect-id,``The section name''>>),
192 consectetur adipiscing elit.
195 This makes the manual page result look like this:
198 Lorem ipsum dolor sit amet (see “The section name”), consectetur
205 Apply the recommendations of the
206 link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style
207 considerations_] section of the LTTng Documentation's contributor's