File: README.md

package info (click to toggle)
ltt-control 2.13.15-2
  • links: PTS, VCS
  • area: main
  • in suites: sid, trixie
  • size: 17,656 kB
  • sloc: ansic: 167,287; sh: 27,018; makefile: 2,828; python: 1,380; yacc: 692; lex: 129; java: 109; perl: 99; cpp: 35; xml: 23
file content (114 lines) | stat: -rw-r--r-- 3,265 bytes parent folder | download
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._).