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 man macro is used to link to another man page. In troff, the man
29 page name is rendered in bold.
31 Usage example: `man:lttng-enable-channel(1)`.
36 The linkgenoptions macro is used to link to the general options
37 section of the `lttng(1)` command.
39 Usage example: `See the linkgenoptions:(general options).`.
44 The option macro is used to write a command-line option which is
45 defined in the same man page.
47 Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
52 Command-line option generating no link. This is used when talking
53 about a generic option which is defined in many man pages.
55 Usage example: `nloption:--jul`
60 General (`lttng(1)`) command-line option, for generating the appropriate
63 Usage example: `genoption:--group`, `genoption:--sessiond-path`
68 The `:not:` macro is used to emphasize on _not_.
73 The `:escwc:` macro is used to output `\*` literally in the man page,
74 which is not so easy to do otherwise.
80 * `common-cmd-footer.txt`: common `lttng` command footer.
81 * `common-cmd-help-options.txt`: common program information section
82 of `lttng` command options.
83 * `common-cmd-options-head.txt`: common `lttng` command head of
85 * `common-footer.txt`: common footer for all commands.
91 Please follow those rules when updating the current man pages or
94 * Always use macros when possible (link to other LTTng man page,
95 command-line option, NOT, etc.).
96 * Use callouts with the `term` role for command-line examples.
97 * Always refer to _long_ options in the text.
98 * Use the `option:--option=parameter` format (with `=`) when providing
99 a parameter to long options.
100 * Write _user space_, not _userspace_ nor _user-space_.
101 (neither _user land_).
102 * Write _file system_, not _filesystem_.
103 * Write _use case_, not _use-case_ nor _usecase_.
104 * Write _log level_, not _loglevel_.
105 * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
106 _LTTng-tools_, not _modules_, _UST_ and _tools_.
107 * Prefer simple emphasis to strong emphasis for emphasizing text.
108 * Try to stay behind the 72th column mark if possible, and behind
109 the 80th column otherwise.
110 * Do not end directory paths with a forward slash
111 (good: `include/trace/events`, bad: `include/trace/events/`).
112 * Minimize the use of the future tense (_will_).
113 * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).