doc/man/Makefile.am: fix top comment
[lttng-tools.git] / doc / man / README.md
CommitLineData
f8cdcb88
PP
1LTTng-tools man pages
2=====================
3
4This directory contains the sources of the LTTng-tools man pages.
5
6LTTng-tools man pages are written in
7[AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to
8DocBook (XML) using the `asciidoc` command, and finally to troff using
9the appropriate DocBook XSL stylesheet (using the `xmlto` command).
10
11
12Custom XSL stylesheets
13----------------------
14
15There are a few custom XSL stylesheets applied for customizing the
16generated man pages in the `xsl` directory.
17
18
19Macros
20------
21
22AsciiDoc is configured with `asciidoc.conf` which contains a few
23macro definitions used everywhere in the man page sources.
24
25
26### linklttng
27
28The linklttng macro is used to link to another LTTng man page. Its
29output is different depending on the back-end. In troff, the man page
30name is rendered in bold, whereas the HTML5 output renders a hyperlink.
31
32Usage example: `linklttng:lttng-enable-channel(1)`.
33
34
8cfee8a5
PP
35### linkgenoptions
36
37The linkgenoptions macro is used to link to the general options
38section of the `lttng(1)` command.
39
40Usage example: `See the linkgenoptions:(general options).`.
41
42
f8cdcb88
PP
43### option
44
b5217c86
PP
45The option macro is used to write a command-line option which is
46defined in the same man page.
f8cdcb88
PP
47
48Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
49
50
b5217c86
PP
51### nloption
52
53Command-line option generating no link. This is used when talking
54about a generic option which is defined in many man pages.
55
56Usage example: `nloption:--jul`
57
58
59### genoption
60
61General (`lttng(1)`) command-line option, for generating the appropriate
62cross-man-page link.
63
64Usage example: `genoption:--group`, `genoption:--sessiond-path`
65
66
f8cdcb88
PP
67### not
68
69The `:not:` macro is used to emphasize on _not_.
70
71
bca82bfe
PP
72### escwc
73
74The `:escwc:` macro is used to output `\*` literally in the man page,
75which is not so easy to do otherwise.
76
77
f8cdcb88
PP
78Includes
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
89Convention
90----------
91
92Please follow those rules when updating the current man pages or
93writing 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._).
This page took 0.02934 seconds and 5 git commands to generate.