[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.


### linklttng

The linklttng macro is used to link to another LTTng man page. Its
output is different depending on the back-end. In troff, the man page
name is rendered in bold, whereas the HTML5 output renders a hyperlink.

Usage example: `linklttng: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_.


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
	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
8cfee8a5 PP	35	### linkgenoptions
	36
	37	The linkgenoptions macro is used to link to the general options
	38	section of the `lttng(1)` command.
	39
	40	Usage example: `See the linkgenoptions:(general options).`.
	41
	42
f8cdcb88 PP	43	### option
f8cdcb88 PP	44
b5217c86 PP	45	The option macro is used to write a command-line option which is
b5217c86 PP	46	defined in the same man page.
f8cdcb88 PP	47
	48	Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
	49
	50
b5217c86 PP	51	### nloption
	52
	53	Command-line option generating no link. This is used when talking
	54	about a generic option which is defined in many man pages.
	55
	56	Usage example: `nloption:--jul`
	57
	58
	59	### genoption
	60
	61	General (`lttng(1)`) command-line option, for generating the appropriate
	62	cross-man-page link.
	63
	64	Usage example: `genoption:--group`, `genoption:--sessiond-path`
	65
	66
f8cdcb88 PP	67	### not
	68
	69	The `:not:` macro is used to emphasize on _not_.
	70
	71
	72	Includes
	73	--------
	74
	75	* `common-cmd-footer.txt`: common `lttng` command footer.
	76	* `common-cmd-help-options.txt`: common program information section
	77	of `lttng` command options.
	78	* `common-cmd-options-head.txt`: common `lttng` command head of
	79	options section.
	80	* `common-footer.txt`: common footer for all commands.
	81
	82
	83	Convention
	84	----------
	85
	86	Please follow those rules when updating the current man pages or
	87	writing new ones:
	88
	89	* Always use macros when possible (link to other LTTng man page,
	90	command-line option, NOT, etc.).
d4f093aa	91	* Use callouts with the `term` role for command-line examples.
f8cdcb88 PP	92	* Always refer to _long_ options in the text.
	93	* Use the `option:--option=parameter` format (with `=`) when providing
	94	a parameter to long options.
	95	* Write _user space_, not _userspace_ nor _user-space_.
	96	(neither _user land_).
	97	* Write _file system_, not _filesystem_.
	98	* Write _use case_, not _use-case_ nor _usecase_.
	99	* Write _log level_, not _loglevel_.
	100	* Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_ and
	101	_LTTng-tools_, not _modules_, _UST_ and _tools_.
	102	* Prefer simple emphasis to strong emphasis for emphasizing text.
	103	* Try to stay behind the 72th column mark if possible, and behind
	104	the 80th column otherwise.
	105	* Do not end directory paths with a forward slash
	106	(good: `include/trace/events`, bad: `include/trace/events/`).
	107	* Minimize the use of the future tense (_will_).
	108	* Do not use Latin abbreviations (_e.g._, _i.e._, _etc._).