lttng-stop(1): add usage examples
[lttng-tools.git] / doc / man / README.md
1 LTTng-tools man pages
2 =====================
3
4 This directory contains the sources of the LTTng-tools man pages.
5
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).
10
11
12 Custom XSL stylesheets
13 ----------------------
14
15 There are a few custom XSL stylesheets applied for customizing the
16 generated man pages in the `xsl` directory.
17
18
19 Macros
20 ------
21
22 AsciiDoc is configured with `asciidoc.conf` which contains a few
23 macro definitions used everywhere in the man page sources.
24
25
26 ### man
27
28 The man macro is used to link to another man page. In troff, the man
29 page name is rendered in bold.
30
31 Usage example: `man:lttng-enable-channel(1)`.
32
33
34 ### linkgenoptions
35
36 The linkgenoptions macro is used to link to the general options
37 section of the `lttng(1)` command.
38
39 Usage example: `See the linkgenoptions:(general options).`.
40
41
42 ### option
43
44 The option macro is used to write a command-line option which is
45 defined in the same man page.
46
47 Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
48
49
50 ### nloption
51
52 Command-line option generating no link. This is used when talking
53 about a generic option which is defined in many man pages.
54
55 Usage example: `nloption:--jul`
56
57
58 ### genoption
59
60 General (`lttng(1)`) command-line option, for generating the appropriate
61 cross-man-page link.
62
63 Usage example: `genoption:--group`, `genoption:--sessiond-path`
64
65
66 ### not
67
68 The `:not:` macro is used to emphasize on _not_.
69
70
71 ### escwc
72
73 The `:escwc:` macro is used to output `\*` literally in the man page,
74 which is not so easy to do otherwise.
75
76
77 Includes
78 --------
79
80 * `common-lttng-cmd-after-options.txt`: common part after the options
81 section of an `lttng` command.
82 * `common-lttng-cmd-help-options.txt`: common program information
83 section of `lttng` command options.
84 * `common-cmd-options-head.txt`: common `lttng` command head of
85 options section.
86 * `common-footer.txt`: common footer for all commands.
87
88
89 Convention
90 ----------
91
92 Please follow those rules when updating the current man pages or
93 writing new ones:
94
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._).
This page took 0.032868 seconds and 4 git commands to generate.