1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
|
LTTng-tools man pages
=====================
This directory contains the sources of the LTTng-tools man pages.
LTTng-tools man pages are written in
[AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to
DocBook (XML) using the `asciidoc` command, and finally to troff using
the appropriate DocBook XSL stylesheet (using the `xmlto` command).
Custom XSL stylesheets
----------------------
There are a few custom XSL stylesheets applied for customizing the
generated man pages in the `xsl` directory.
Macros
------
AsciiDoc is configured with `asciidoc.conf` which contains a few
macro definitions used everywhere in the man page sources.
### man
The man macro is used to link to another man page. In troff, the man
page name is rendered in bold.
Usage example: `man:lttng-enable-channel(1)`.
### linkgenoptions
The linkgenoptions macro is used to link to the general options
section of the `lttng(1)` command.
Usage example: `See the linkgenoptions:(general options).`.
### option
The option macro is used to write a command-line option which is
defined in the same man page.
Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
### nloption
Command-line option generating no link. This is used when talking
about a generic option which is defined in many man pages.
Usage example: `nloption:--jul`
### genoption
General (`lttng(1)`) command-line option, for generating the appropriate
cross-man-page link.
Usage example: `genoption:--group`, `genoption:--sessiond-path`
### not
The `:not:` macro is used to emphasize on _not_.
### escwc
The `:escwc:` macro is used to output `\*` literally in the man page,
which is not so easy to do otherwise.
Includes
--------
* `common-lttng-cmd-after-options.txt`: common part after the options
section of an `lttng` command.
* `common-lttng-cmd-help-options.txt`: common program information
section of `lttng` command options.
* `common-cmd-options-head.txt`: common `lttng` command head of
options section.
* `common-footer.txt`: common footer for all commands.
Convention
----------
Please follow those rules when updating the current man pages or
writing new ones:
* Always use macros when possible (link to other LTTng man page,
command-line option, NOT, etc.).
* Use callouts with the `term` role for command-line examples.
* Always refer to _long_ options in the text.
* Use the `option:--option=parameter` format (with `=`) when providing
a parameter to long options.
* Write _user space_, not _userspace_ nor _user-space_.
(neither _user land_).
* Write _file system_, not _filesystem_.
* Write _use case_, not _use-case_ nor _usecase_.
* Write _log level_, not _loglevel_.
* Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
_LTTng-tools_, not _modules_, _UST_ and _tools_.
* Prefer simple emphasis to strong emphasis for emphasizing text.
* Try to stay behind the 72th column mark if possible, and behind
the 80th column otherwise.
* Do not end directory paths with a forward slash
(good: `include/trace/events`, bad: `include/trace/events/`).
* Minimize the use of the future tense (_will_).
* Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).
|