5 This directory contains the sources of the Babeltrace man pages.
7 The Babeltrace man pages are written in
8 http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
9 DocBook (XML) using the `asciidoc` command, and finally to troff using
10 the appropriate DocBook XSL stylesheet (using the `xmlto` command).
18 `babeltrace(1)` command::
19 +babeltrace-__command__.1.txt+
21 Babeltrace introduction::
22 `babeltrace-intro.7.txt`
25 +babeltrace-plugin-__plugin__.7.txt+
27 Babeltrace plugin's component class::
28 +babeltrace-__type__.__plugin__.__compcls__.7.txt+
33 AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
34 macro definitions used everywhere in the man page sources:
36 +man:__page__(__section__)+::
37 Use this macro to insert a link to another man page named
38 +__page__+ in section +__section__+. In troff, the man page's name
41 Example: `man:babeltrace-convert(1)`
44 Use this macro to insert a link to the command-line option
45 +__name__+ described in an _OPTIONS_ section in the same man page.
47 Example: `opt:--verbose`, `opt:--color='WHEN'`
49 +manopt:__page__(__section__):__name__+::
50 Use this macro to insert a link to the command-line option
51 +__name__+ described in the _OPTIONS_ section of another Babeltrace
52 or LTTng man page named +__page__+ in section +__section__+.
54 Example: `manopt:babeltrace(1):--log-level`,
55 +manopt:babeltrace-convert(1):--component=\`source.ctf.fs`+
58 Use this macro to write a command-line option named +__name__+
59 without inserting a link. The option does not need to be described
62 Example: `nlopt:--help`
65 Use this macro to insert a link to the component initialization
66 parameter named +__name__+ described in an _INITIALIZATION
67 PARAMETERS_ section in the same man page.
69 Example: `param:begin`, `param:path='PATH'`
71 +manparam:__type__.__plug__.__compclsname__:__paramname__+::
72 Use this macro to insert a link to the component initialization
73 parameter +__paramname__+ described in the _INITIALIZATION
74 PARAMETERS_ section of the man page of another Babeltrace component
75 class. The component class has the type +__type__+, is found in the
76 plugin named +__plug__+ and is named +__name__+.
78 Example: `manparam:filter.utils.trimmer:begin`,
79 `manparam:source.ctf.fs:path`
82 Use this macro to write a component initialization parameter named
83 +__name__+ without inserting a link. The parameter does not need to
84 be described in the same man page.
86 Example: `nlparam:end`
88 +compcls:__type__.__plug__.__name__+::
89 Use this macro to write a component class specification. The
90 component class has the type +__type__+, is found in the plugin
91 named +__plug__+ and is named +__name__+.
93 Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
96 Use `:not:` to emphasize _not_.
99 Use `:escstar:` to insert `\*` literally.
102 Use `:esccomma:` to insert `\,` literally.
105 Use `:escdot:` to insert `\.` literally.
111 Each man page must set this attribute to the type (lowercase) of the
112 man page: `program`, `command`, `plugin`, or `component class`. It's
113 used in various included files to output a text that is more
117 Each man page should have its own revision date with the following
118 https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
121 Make sure to update this date when you update a given man page. We are
122 not generating the date automatically because we want the real last
123 revision date in the man page, not the last build date.
125 Also see `asciidoc-attrs.conf` which is generated by `config.status`
126 from `asciidoc-attrs.conf.in`. This file contains fixed and
127 configuration-dependent attributes which you can use anywhere in the
133 Apply the recommendations of the
134 link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style
135 considerations_] section of the LTTng Documentation's contributor's