projects / lttng-tools.git / blame
| 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 | ||
| 35 | ### option | |
| 36 | ||
| 37 | The option macro is used to write a command-line option. | |
| 38 | ||
| 39 | Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING` | |
| 40 | ||
| 41 | ||
| 42 | ### not | |
| 43 | ||
| 44 | The `:not:` macro is used to emphasize on _not_. | |
| 45 | ||
| 46 | ||
| 47 | Includes | |
| 48 | -------- | |
| 49 | ||
| 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 | |
| 54 | options section. | |
| 55 | * `common-footer.txt`: common footer for all commands. | |
| 56 | ||
| 57 | ||
| 58 | Convention | |
| 59 | ---------- | |
| 60 | ||
| 61 | Please follow those rules when updating the current man pages or | |
| 62 | writing new ones: | |
| 63 | ||
| 64 | * Always use macros when possible (link to other LTTng man page, | |
| 65 | command-line option, NOT, etc.). | |
| 66 | * Use callouts 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._). |