[lttng-tools.git] / doc / man / README.md

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-cmd-footer.txt`: common `lttng` command footer.
  * `common-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._).
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
7c1a4458	26	### man
f8cdcb88	27
7c1a4458 PP	28	The man macro is used to link to another man page. In troff, the man
7c1a4458 PP	29	page name is rendered in bold.
f8cdcb88	30
7c1a4458	31	Usage example: `man:lttng-enable-channel(1)`.
f8cdcb88 PP	32
f8cdcb88 PP	33
8cfee8a5 PP	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
f8cdcb88 PP	42	### option
f8cdcb88 PP	43
b5217c86 PP	44	The option macro is used to write a command-line option which is
b5217c86 PP	45	defined in the same man page.
f8cdcb88 PP	46
	47	Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
	48
	49
b5217c86 PP	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
f8cdcb88 PP	66	### not
	67
	68	The `:not:` macro is used to emphasize on _not_.
	69
	70
bca82bfe PP	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
f8cdcb88 PP	77	Includes
	78	--------
	79
	80	* `common-cmd-footer.txt`: common `lttng` command footer.
	81	* `common-cmd-help-options.txt`: common program information section
	82	of `lttng` command options.
	83	* `common-cmd-options-head.txt`: common `lttng` command head of
	84	options section.
	85	* `common-footer.txt`: common footer for all commands.
	86
	87
	88	Convention
	89	----------
	90
	91	Please follow those rules when updating the current man pages or
	92	writing new ones:
	93
	94	* Always use macros when possible (link to other LTTng man page,
	95	command-line option, NOT, etc.).
d4f093aa	96	* Use callouts with the `term` role for command-line examples.
f8cdcb88 PP	97	* Always refer to _long_ options in the text.
	98	* Use the `option:--option=parameter` format (with `=`) when providing
	99	a parameter to long options.
	100	* Write _user space_, not _userspace_ nor _user-space_.
	101	(neither _user land_).
	102	* Write _file system_, not _filesystem_.
	103	* Write _use case_, not _use-case_ nor _usecase_.
	104	* Write _log level_, not _loglevel_.
	105	* Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
	106	_LTTng-tools_, not _modules_, _UST_ and _tools_.
	107	* Prefer simple emphasis to strong emphasis for emphasizing text.
	108	* Try to stay behind the 72th column mark if possible, and behind
	109	the 80th column otherwise.
	110	* Do not end directory paths with a forward slash
	111	(good: `include/trace/events`, bad: `include/trace/events/`).
	112	* Minimize the use of the future tense (_will_).
	113	* Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).