doc/man/README.adoc

   1 // Render with Asciidoctor
   2
   3 = Babeltrace{nbsp}2 manual pages
   4 Philippe Proulx
   5 4 September 2019
   6 :toc:
   7
   8 This directory contains the sources of the Babeltrace{nbsp}2 manual
   9 pages.
  10
  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).
  15
  16
  17 == Naming
  18
  19 Main program::
  20     `__program__.1.txt`
  21
  22 Specific `babeltrace2(1)` command::
  23     `babeltrace2-__command__.1.txt`
  24
  25 Babeltrace{nbsp}2 introduction::
  26     `babeltrace2-intro.7.txt`
  27
  28 Babeltrace{nbsp}2 plugin::
  29     `babeltrace2-plugin-__plugin-name__.7.txt`
  30
  31 Babeltrace{nbsp}2 component class::
  32     `babeltrace2-__type__.__plugin-name__.__comp-cls-name__.7.txt`
  33
  34 Babeltrace{nbsp}2 query object::
  35     `babeltrace2-query-__query-object-name__.7.txt`
  36
  37
  38 == Macros
  39
  40 AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
  41 macro definitions used everywhere in the manual page sources:
  42
  43 Other manual page::
  44 +
  45 --
  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.
  49 +
  50 Example: `man:babeltrace2-convert(1)`
  51 --
  52
  53 Command-line option::
  54 +
  55 --
  56 `opt:__name__`::
  57     Insert a link to the command-line option `__name__` described in the
  58     _OPTIONS_ section in the same manual page.
  59 +
  60 Examples: `opt:--verbose`, `+opt:--color='WHEN'+`
  61
  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__`.
  66 +
  67 Examples: `manopt:babeltrace2(1):--log-level`,
  68 `+manopt:babeltrace2-convert(1):--component=pass:[`source.ctf.fs`]+`
  69
  70 `nlopt:__name__`::
  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
  73     page.
  74 +
  75 Examples: `nlopt:--help`, `+nlopt:--log-level='LEVEL'+`
  76 --
  77
  78 Component initialization or query parameter::
  79 +
  80 --
  81 `param:__name__`::
  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.
  85 +
  86 Examples: `param:begin`, `+param:inputs='PATHS'+`
  87
  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
  94     `__comp-cls-name__`.
  95 +
  96 Examples: `manparam:filter.utils.trimmer:begin`,
  97 `manparam:source.ctf.fs:inputs`
  98
  99 `nlparam:__name__`::
 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.
 103 +
 104 Example: `nlparam:end`
 105
 106 `qres:__name__`::
 107     Insert a link to the query result object entry named `__name__`
 108     described in a _RESULT OBJECT_ section in the same manual page.
 109 +
 110 Examples: `qres:input`, `+qres:group='GROUP'+`
 111
 112 `nlqres:__name__`::
 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
 115     page.
 116 +
 117 Example: `nlqres:group`
 118
 119 `vtype:[__type__]`::
 120     Write a value object type `__type__`.
 121 +
 122 Examples: `vtype:[optional boolean]`, `vtype:[signed integer or string]`
 123 --
 124
 125 Component class::
 126 +
 127 --
 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__`.
 132 +
 133 Examples: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
 134 --
 135
 136 Text emphasis and replacement::
 137 +
 138 --
 139 `:all:`::
 140     Emphasize "`all`".
 141
 142 `:not:`::
 143     Emphasize "`not`".
 144
 145 `:escstar:`::
 146     Insert `+\*+` literally.
 147
 148 `:esccomma:`::
 149     Insert `+\,+` literally.
 150
 151 `:escdot:`::
 152     Insert `+\.+` literally.
 153 --
 154
 155
 156 == Attributes
 157
 158 `manpagetype`::
 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
 162     more targeted.
 163
 164 `revdate`::
 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]:
 167     _28 October 1987_.
 168 +
 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.
 172
 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
 176 sources.
 177
 178
 179 == Internal links
 180
 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.
 185
 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
 188 it:
 189
 190 ----
 191 Lorem ipsum dolor sit amet (see <<sect-id,``The section name''>>),
 192 consectetur adipiscing elit.
 193 ----
 194
 195 This makes the manual page result look like this:
 196
 197 ----
 198        Lorem ipsum dolor sit amet (see “The section name”), consectetur
 199        adipiscing elit.
 200 ----
 201
 202
 203 == Style
 204
 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
 208 guide.