4 This directory contains the sources of the LTTng-tools man pages.
6 LTTng-tools man pages are written in
7 [AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to
8 DocBook (XML) using the `asciidoc` command, and finally to troff using
9 the appropriate DocBook XSL stylesheet (using the `xmlto` command).
12 Custom XSL stylesheets
13 ----------------------
15 There are a few custom XSL stylesheets applied for customizing the
16 generated man pages in the `xsl` directory.
22 AsciiDoc is configured with `asciidoc.conf` which contains a few
23 macro definitions used everywhere in the man page sources.
28 The linklttng macro is used to link to another LTTng man page. Its
29 output is different depending on the back-end. In troff, the man page
30 name is rendered in bold, whereas the HTML5 output renders a hyperlink.
32 Usage example: `linklttng:lttng-enable-channel(1)`.
37 The linkgenoptions macro is used to link to the general options
38 section of the `lttng(1)` command.
40 Usage example: `See the linkgenoptions:(general options).`.
45 The option macro is used to write a command-line option which is
46 defined in the same man page.
48 Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
53 Command-line option generating no link. This is used when talking
54 about a generic option which is defined in many man pages.
56 Usage example: `nloption:--jul`
61 General (`lttng(1)`) command-line option, for generating the appropriate
64 Usage example: `genoption:--group`, `genoption:--sessiond-path`
69 The `:not:` macro is used to emphasize on _not_.
75 * `common-cmd-footer.txt`: common `lttng` command footer.
76 * `common-cmd-help-options.txt`: common program information section
77 of `lttng` command options.
78 * `common-cmd-options-head.txt`: common `lttng` command head of
80 * `common-footer.txt`: common footer for all commands.
86 Please follow those rules when updating the current man pages or
89 * Always use macros when possible (link to other LTTng man page,
90 command-line option, NOT, etc.).
91 * Use callouts with the `term` role for command-line examples.
92 * Always refer to _long_ options in the text.
93 * Use the `option:--option=parameter` format (with `=`) when providing
94 a parameter to long options.
95 * Write _user space_, not _userspace_ nor _user-space_.
96 (neither _user land_).
97 * Write _file system_, not _filesystem_.
98 * Write _use case_, not _use-case_ nor _usecase_.
99 * Write _log level_, not _loglevel_.
100 * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
101 _LTTng-tools_, not _modules_, _UST_ and _tools_.
102 * Prefer simple emphasis to strong emphasis for emphasizing text.
103 * Try to stay behind the 72th column mark if possible, and behind
104 the 80th column otherwise.
105 * Do not end directory paths with a forward slash
106 (good: `include/trace/events`, bad: `include/trace/events/`).
107 * Minimize the use of the future tense (_will_).
108 * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).