Commit | Line | Data |
---|---|---|
e03d7c66 MJ |
1 | <!-- |
2 | SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com> | |
3 | ||
4 | SPDX-License-Identifier: CC-BY-4.0 | |
5 | --> | |
6 | ||
4ddbd0b7 PP |
7 | LTTng-UST man pages |
8 | =================== | |
9 | ||
10 | This directory contains the sources of the LTTng-UST man pages. | |
11 | ||
12 | LTTng-UST man pages are written in | |
13 | [AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to | |
14 | DocBook (XML) using the `asciidoc` command, and finally to troff using | |
15 | the appropriate DocBook XSL stylesheet (using the `xmlto` command). | |
16 | ||
17 | ||
18 | Custom XSL stylesheets | |
19 | ---------------------- | |
20 | ||
21 | There are a few custom XSL stylesheets applied for customizing the | |
22 | generated man pages in the `xsl` directory. | |
23 | ||
24 | ||
25 | Macros | |
26 | ------ | |
27 | ||
28 | AsciiDoc is configured with `asciidoc.conf` which contains a few | |
29 | macro definitions used everywhere in the man page sources. | |
30 | ||
31 | ||
32 | ### `man` | |
33 | ||
34 | The `man` macro is used to specify a reference to another man page. | |
35 | Using the provided `asciidoc.conf` configuration file, the man page | |
36 | name is rendered in bold and the section is normal. | |
37 | ||
38 | Usage example: `man:lttng-enable-channel(1)`, `man:dlopen(3)` | |
39 | ||
40 | ||
41 | ### `option` | |
42 | ||
43 | The option macro is used to write a command-line option which is | |
44 | **defined in the same man page**. | |
45 | ||
46 | Usage example: `option:--output`, `option:--verbose` | |
47 | ||
48 | ||
49 | ### `nloption` | |
50 | ||
51 | Command-line option generating no link. This is used when writing | |
52 | about an option which is **not defined in the same man page**. | |
53 | ||
54 | Usage example: `nloption:-finstrument-functions` | |
55 | ||
56 | ||
57 | ### `not` | |
58 | ||
59 | The `:not:` macro is used to emphasize on _not_. | |
60 | ||
61 | ||
62 | Includes | |
63 | -------- | |
64 | ||
65 | * `common-authors.txt`: common authors section of the LTTng-UST | |
66 | project. Only use this for man pages which describe | |
67 | a command/library/function written by the main authors of LTTng-UST. | |
68 | * `common-copyright.txt`: common copyrights section of the LTTng-UST | |
69 | project. Only use this for man pages which describe | |
70 | a command/library/function having the common LTTng-UST license. | |
71 | * `common-footer.txt`: common footer for all man pages. This goes | |
72 | before the copyrights section. | |
73 | * `log-levels.txt`: definition list of LTTng-UST log levels. | |
74 | * `tracef-tracelog-limitations.txt`: limitations that apply to both | |
5b1163c6 | 75 | the `lttng_ust_tracef(3)` and `lttng_ust_tracelog(3)` man pages. |
4ddbd0b7 PP |
76 | |
77 | ||
78 | Convention | |
79 | ---------- | |
80 | ||
81 | Please follow those rules when updating the current man pages or writing | |
82 | new ones: | |
83 | ||
84 | * Always use macros when possible (man page references, command-line | |
85 | options, _not_, etc.). | |
86 | * Use callouts with the `term` role for command-line examples. | |
87 | * Use a verse, possibly with the `term` role, in the synopsis section. | |
88 | * Always refer to _long_ options in the text. | |
89 | * Use the `option:--option='PARAM'` format (with `=`) when providing a | |
90 | parameter to long options. | |
91 | * Prefer writing _user space_ rather than _userspace_, _user-space_, | |
92 | or _user land_. | |
93 | * Write _file system_, not _filesystem_. | |
94 | * Prefer writing _use case_ rather than _use-case_ or _usecase_. | |
95 | * Write _log level_, not _loglevel_. | |
96 | * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_, | |
97 | and _LTTng-tools_, not _modules_, _UST_ and _tools_. | |
98 | * Prefer simple emphasis to strong emphasis for emphasizing text. | |
99 | * Try to stay behind the 72th column mark if possible, and behind the | |
100 | 80th column otherwise. | |
101 | * Do not end directory paths with a forward slash (good: | |
102 | `include/trace/events`, bad: `include/trace/events/`). | |
103 | * Minimize the use of the future tense (_will_). | |
104 | * Use an active voice, and prefer using the second person (_you_) when | |
105 | referring to the user. | |
106 | * Avoid using Latin abbreviations (_e.g._, _i.e._, _etc._). |