| 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. |