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 option macro is used to write a command-line option.
39 Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
44 The `:not:` macro is used to emphasize on _not_.
50 * `common-cmd-footer.txt`: common `lttng` command footer.
51 * `common-cmd-help-options.txt`: common program information section
52 of `lttng` command options.
53 * `common-cmd-options-head.txt`: common `lttng` command head of
55 * `common-footer.txt`: common footer for all commands.
61 Please follow those rules when updating the current man pages or
64 * Always use macros when possible (link to other LTTng man page,
65 command-line option, NOT, etc.).
66 * Use callouts with the `term` role for command-line examples.
67 * Always refer to _long_ options in the text.
68 * Use the `option:--option=parameter` format (with `=`) when providing
69 a parameter to long options.
70 * Write _user space_, not _userspace_ nor _user-space_.
71 (neither _user land_).
72 * Write _file system_, not _filesystem_.
73 * Write _use case_, not _use-case_ nor _usecase_.
74 * Write _log level_, not _loglevel_.
75 * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
76 _LTTng-tools_, not _modules_, _UST_ and _tools_.
77 * Prefer simple emphasis to strong emphasis for emphasizing text.
78 * Try to stay behind the 72th column mark if possible, and behind
79 the 80th column otherwise.
80 * Do not end directory paths with a forward slash
81 (good: `include/trace/events`, bad: `include/trace/events/`).
82 * Minimize the use of the future tense (_will_).
83 * Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).