// 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 <>), 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.