Commit | Line | Data |
---|---|---|
f8cdcb88 PP |
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 | ### linklttng | |
27 | ||
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. | |
31 | ||
32 | Usage example: `linklttng:lttng-enable-channel(1)`. | |
33 | ||
34 | ||
8cfee8a5 PP |
35 | ### linkgenoptions |
36 | ||
37 | The linkgenoptions macro is used to link to the general options | |
38 | section of the `lttng(1)` command. | |
39 | ||
40 | Usage example: `See the linkgenoptions:(general options).`. | |
41 | ||
42 | ||
f8cdcb88 PP |
43 | ### option |
44 | ||
b5217c86 PP |
45 | The option macro is used to write a command-line option which is |
46 | defined in the same man page. | |
f8cdcb88 PP |
47 | |
48 | Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING` | |
49 | ||
50 | ||
b5217c86 PP |
51 | ### nloption |
52 | ||
53 | Command-line option generating no link. This is used when talking | |
54 | about a generic option which is defined in many man pages. | |
55 | ||
56 | Usage example: `nloption:--jul` | |
57 | ||
58 | ||
59 | ### genoption | |
60 | ||
61 | General (`lttng(1)`) command-line option, for generating the appropriate | |
62 | cross-man-page link. | |
63 | ||
64 | Usage example: `genoption:--group`, `genoption:--sessiond-path` | |
65 | ||
66 | ||
f8cdcb88 PP |
67 | ### not |
68 | ||
69 | The `:not:` macro is used to emphasize on _not_. | |
70 | ||
71 | ||
bca82bfe PP |
72 | ### escwc |
73 | ||
74 | The `:escwc:` macro is used to output `\*` literally in the man page, | |
75 | which is not so easy to do otherwise. | |
76 | ||
77 | ||
f8cdcb88 PP |
78 | Includes |
79 | -------- | |
80 | ||
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 | |
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.). | |
d4f093aa | 97 | * Use callouts with the `term` role for command-line examples. |
f8cdcb88 PP |
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._). |