Commit | Line | Data |
---|---|---|
e70712b3 PP |
1 | // Render with Asciidoctor |
2 | ||
3 | = Babeltrace{nbsp}2 manual pages | |
0659f3af | 4 | Philippe Proulx |
e70712b3 PP |
5 | 4 September 2019 |
6 | :toc: | |
0659f3af | 7 | |
e70712b3 PP |
8 | This directory contains the sources of the Babeltrace{nbsp}2 manual |
9 | pages. | |
0659f3af | 10 | |
e70712b3 PP |
11 | The Babeltrace{nbsp}2 manual pages are written in |
12 | https://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to | |
0659f3af PP |
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:: | |
e70712b3 | 20 | `__program__.1.txt` |
0659f3af | 21 | |
e70712b3 PP |
22 | Specific `babeltrace2(1)` command:: |
23 | `babeltrace2-__command__.1.txt` | |
0659f3af | 24 | |
e70712b3 | 25 | Babeltrace{nbsp}2 introduction:: |
a8be4294 | 26 | `babeltrace2-intro.7.txt` |
0659f3af | 27 | |
e70712b3 PP |
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` | |
0659f3af | 33 | |
e70712b3 PP |
34 | Babeltrace{nbsp}2 query object:: |
35 | `babeltrace2-query-__query-object-name__.7.txt` | |
0659f3af PP |
36 | |
37 | ||
38 | == Macros | |
39 | ||
40 | AsciiDoc is configured with `bt-asciidoc.conf` which contains a few | |
e70712b3 | 41 | macro definitions used everywhere in the manual page sources: |
0659f3af | 42 | |
e70712b3 PP |
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. | |
0659f3af | 49 | + |
a8be4294 | 50 | Example: `man:babeltrace2-convert(1)` |
e70712b3 | 51 | -- |
0659f3af | 52 | |
e70712b3 | 53 | Command-line option:: |
0659f3af | 54 | + |
e70712b3 PP |
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. | |
0659f3af | 59 | + |
e70712b3 | 60 | Examples: `opt:--verbose`, `+opt:--color='WHEN'+` |
0659f3af | 61 | |
e70712b3 PP |
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__`. | |
0659f3af | 66 | + |
e70712b3 PP |
67 | Examples: `manopt:babeltrace2(1):--log-level`, |
68 | `+manopt:babeltrace2-convert(1):--component=pass:[`source.ctf.fs`]+` | |
0659f3af | 69 | |
e70712b3 PP |
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. | |
0659f3af | 74 | + |
e70712b3 PP |
75 | Examples: `nlopt:--help`, `+nlopt:--log-level='LEVEL'+` |
76 | -- | |
0659f3af | 77 | |
e70712b3 PP |
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__`. | |
0659f3af | 95 | + |
e70712b3 PP |
96 | Examples: `manparam:filter.utils.trimmer:begin`, |
97 | `manparam:source.ctf.fs:inputs` | |
0659f3af | 98 | |
e70712b3 PP |
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. | |
0659f3af PP |
103 | + |
104 | Example: `nlparam:end` | |
105 | ||
e70712b3 PP |
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:: | |
0659f3af | 137 | + |
e70712b3 PP |
138 | -- |
139 | `:all:`:: | |
140 | Emphasize "`all`". | |
0659f3af PP |
141 | |
142 | `:not:`:: | |
e70712b3 | 143 | Emphasize "`not`". |
0659f3af PP |
144 | |
145 | `:escstar:`:: | |
e70712b3 | 146 | Insert `+\*+` literally. |
0659f3af PP |
147 | |
148 | `:esccomma:`:: | |
e70712b3 | 149 | Insert `+\,+` literally. |
0659f3af PP |
150 | |
151 | `:escdot:`:: | |
e70712b3 PP |
152 | Insert `+\.+` literally. |
153 | -- | |
0659f3af PP |
154 | |
155 | ||
156 | == Attributes | |
157 | ||
158 | `manpagetype`:: | |
e70712b3 PP |
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. | |
0659f3af PP |
163 | |
164 | `revdate`:: | |
e70712b3 | 165 | Each manual page must have its own revision date with the following |
0659f3af PP |
166 | https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]: |
167 | _28 October 1987_. | |
168 | + | |
e70712b3 PP |
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. | |
0659f3af PP |
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 | ||
e70712b3 PP |
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 | ||
0659f3af PP |
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. |