Commit | Line | Data |
---|---|---|
0659f3af PP |
1 | = Babeltrace man pages |
2 | Philippe Proulx | |
3 | 4 October 2017 | |
4 | ||
5 | This directory contains the sources of the Babeltrace man pages. | |
6 | ||
7 | The Babeltrace man pages are written in | |
8 | http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to | |
9 | DocBook (XML) using the `asciidoc` command, and finally to troff using | |
10 | the appropriate DocBook XSL stylesheet (using the `xmlto` command). | |
11 | ||
12 | ||
13 | == Naming | |
14 | ||
15 | Main program:: | |
16 | +__program__.1.txt+ | |
17 | ||
18 | `babeltrace(1)` command:: | |
19 | +babeltrace-__command__.1.txt+ | |
20 | ||
21 | Babeltrace introduction:: | |
22 | `babeltrace-intro.7.txt` | |
23 | ||
24 | Babeltrace plugin:: | |
25 | +babeltrace-plugin-__plugin__.7.txt+ | |
26 | ||
27 | Babeltrace plugin's component class:: | |
28 | +babeltrace-__type__.__plugin__.__compcls__.7.txt+ | |
29 | ||
30 | ||
31 | == Macros | |
32 | ||
33 | AsciiDoc is configured with `bt-asciidoc.conf` which contains a few | |
34 | macro definitions used everywhere in the man page sources: | |
35 | ||
36 | +man:__page__(__section__)+:: | |
37 | Use this macro to insert a link to another man page named | |
38 | +__page__+ in section +__section__+. In troff, the man page's name | |
39 | is rendered in bold. | |
40 | + | |
41 | Example: `man:babeltrace-convert(1)` | |
42 | ||
43 | +opt:__name__+:: | |
44 | Use this macro to insert a link to the command-line option | |
45 | +__name__+ described in an _OPTIONS_ section in the same man page. | |
46 | + | |
47 | Example: `opt:--verbose`, `opt:--color='WHEN'` | |
48 | ||
49 | +manopt:__page__(__section__):__name__+:: | |
50 | Use this macro to insert a link to the command-line option | |
51 | +__name__+ described in the _OPTIONS_ section of another Babeltrace | |
52 | or LTTng man page named +__page__+ in section +__section__+. | |
53 | + | |
54 | Example: `manopt:babeltrace(1):--log-level`, | |
55 | +manopt:babeltrace-convert(1):--component=\`source.ctf.fs`+ | |
56 | ||
57 | +nlopt:__name__+:: | |
58 | Use this macro to write a command-line option named +__name__+ | |
59 | without inserting a link. The option does not need to be described | |
60 | in the same man page. | |
61 | + | |
62 | Example: `nlopt:--help` | |
63 | ||
64 | +param:__name__+:: | |
65 | Use this macro to insert a link to the component initialization | |
66 | parameter named +__name__+ described in an _INITIALIZATION | |
67 | PARAMETERS_ section in the same man page. | |
68 | + | |
69 | Example: `param:begin`, `param:path='PATH'` | |
70 | ||
71 | +manparam:__type__.__plug__.__compclsname__:__paramname__+:: | |
72 | Use this macro to insert a link to the component initialization | |
73 | parameter +__paramname__+ described in the _INITIALIZATION | |
74 | PARAMETERS_ section of the man page of another Babeltrace component | |
75 | class. The component class has the type +__type__+, is found in the | |
76 | plugin named +__plug__+ and is named +__name__+. | |
77 | + | |
78 | Example: `manparam:filter.utils.trimmer:begin`, | |
79 | `manparam:source.ctf.fs:path` | |
80 | ||
81 | +nlparam:__name__+:: | |
82 | Use this macro to write a component initialization parameter named | |
83 | +__name__+ without inserting a link. The parameter does not need to | |
84 | be described in the same man page. | |
85 | + | |
86 | Example: `nlparam:end` | |
87 | ||
88 | +compcls:__type__.__plug__.__name__+:: | |
89 | Use this macro to write a component class specification. The | |
90 | component class has the type +__type__+, is found in the plugin | |
91 | named +__plug__+ and is named +__name__+. | |
92 | + | |
93 | Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer` | |
94 | ||
95 | `:not:`:: | |
96 | Use `:not:` to emphasize _not_. | |
97 | ||
98 | `:escstar:`:: | |
99 | Use `:escstar:` to insert `\*` literally. | |
100 | ||
101 | `:esccomma:`:: | |
102 | Use `:esccomma:` to insert `\,` literally. | |
103 | ||
104 | `:escdot:`:: | |
105 | Use `:escdot:` to insert `\.` literally. | |
106 | ||
107 | ||
108 | == Attributes | |
109 | ||
110 | `manpagetype`:: | |
111 | Each man page must set this attribute to the type (lowercase) of the | |
112 | man page: `program`, `command`, `plugin`, or `component class`. It's | |
113 | used in various included files to output a text that is more | |
114 | targeted. | |
115 | ||
116 | `revdate`:: | |
117 | Each man page should have its own revision date with the following | |
118 | https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]: | |
119 | _28 October 1987_. | |
120 | + | |
121 | Make sure to update this date when you update a given man page. We are | |
122 | not generating the date automatically because we want the real last | |
123 | revision date in the man page, not the last build date. | |
124 | ||
125 | Also see `asciidoc-attrs.conf` which is generated by `config.status` | |
126 | from `asciidoc-attrs.conf.in`. This file contains fixed and | |
127 | configuration-dependent attributes which you can use anywhere in the | |
128 | sources. | |
129 | ||
130 | ||
131 | == Style | |
132 | ||
133 | Apply the recommendations of the | |
134 | link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style | |
135 | considerations_] section of the LTTng Documentation's contributor's | |
136 | guide. |