| 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._). |