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_.
74 The `:escwc:` macro is used to output `\*` literally in the man page,
75 which is not so easy to do otherwise.
81 * `common-cmd-footer.txt`: common `lttng` command footer.
82 * `common-cmd-help-options.txt`: common program information section
83 of `lttng` command options.
84 * `common-cmd-options-head.txt`: common `lttng` command head of
86 * `common-footer.txt`: common footer for all commands.
92 Please follow those rules when updating the current man pages or
95 * Always use macros when possible (link to other LTTng man page,
96 command-line option, NOT, etc.).
97 * Use callouts with the `term` role for command-line examples.
98 * Always refer to _long_ options in the text.
99 * Use the `option:--option=parameter` format (with `=`) when providing
100 a parameter to long options.
101 * Write _user space_, not _userspace_ nor _user-space_.
102 (neither _user land_).
103 * Write _file system_, not _filesystem_.
104 * Write _use case_, not _use-case_ nor _usecase_.
105 * Write _log level_, not _loglevel_.
106 * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
107 _LTTng-tools_, not _modules_, _UST_ and _tools_.
108 * Prefer simple emphasis to strong emphasis for emphasizing text.
109 * Try to stay behind the 72th column mark if possible, and behind
110 the 80th column otherwise.
111 * Do not end directory paths with a forward slash
112 (good: `include/trace/events`, bad: `include/trace/events/`).
113 * Minimize the use of the future tense (_will_).
114 * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).