-= Babeltrace man pages
+// Render with Asciidoctor
+
+= Babeltrace{nbsp}2 manual pages
Philippe Proulx
-4 October 2017
+4 September 2019
+:toc:
-This directory contains the sources of the Babeltrace man pages.
+This directory contains the sources of the Babeltrace{nbsp}2 manual
+pages.
-The Babeltrace man pages are written in
-http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
+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+
+ `__program__.1.txt`
-`babeltrace2(1)` command::
- +babeltrace2-__command__.1.txt+
+Specific `babeltrace2(1)` command::
+ `babeltrace2-__command__.1.txt`
-Babeltrace introduction::
+Babeltrace{nbsp}2 introduction::
`babeltrace2-intro.7.txt`
-Babeltrace plugin::
- +babeltrace2-plugin-__plugin__.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 plugin's component class::
- +babeltrace2-__type__.__plugin__.__compcls__.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 man page sources:
+macro definitions used everywhere in the manual 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.
+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)`
+--
-+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.
+Command-line option::
+
-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__+.
+--
+`opt:__name__`::
+ Insert a link to the command-line option `__name__` described in the
+ _OPTIONS_ section in the same manual page.
+
-Example: `manopt:babeltrace2(1):--log-level`,
-+manopt:babeltrace2-convert(1):--component=\`source.ctf.fs`+
+Examples: `opt:--verbose`, `+opt:--color='WHEN'+`
-+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.
+`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__`.
+
-Example: `nlopt:--help`
+Examples: `manopt:babeltrace2(1):--log-level`,
+`+manopt:babeltrace2-convert(1):--component=pass:[`source.ctf.fs`]+`
-+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.
+`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.
+
-Example: `param:begin`, `param:path='PATH'`
+Examples: `nlopt:--help`, `+nlopt:--log-level='LEVEL'+`
+--
-+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__+.
+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__`.
+
-Example: `manparam:filter.utils.trimmer:begin`,
-`manparam:source.ctf.fs:path`
+Examples: `manparam:filter.utils.trimmer:begin`,
+`manparam:source.ctf.fs:inputs`
-+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.
+`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`
-+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__+.
+`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::
+
-Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
+--
+`:all:`::
+ Emphasize "`all`".
`:not:`::
- Use `:not:` to emphasize _not_.
+ Emphasize "`not`".
`:escstar:`::
- Use `:escstar:` to insert `\*` literally.
+ Insert `+\*+` literally.
`:esccomma:`::
- Use `:esccomma:` to insert `\,` literally.
+ Insert `+\,+` literally.
`:escdot:`::
- Use `:escdot:` to insert `\.` literally.
+ 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.
+ 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 man page should have its own revision date with the following
+ 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 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.
+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
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
projects / babeltrace.git / blobdiff