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

LTTng-UST man pages
===================

This directory contains the sources of the LTTng-UST man pages.

LTTng-UST 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 specify a reference to another man page.
Using the provided `asciidoc.conf` configuration file, the man page
name is rendered in bold and the section is normal.

Usage example: `man:lttng-enable-channel(1)`, `man:dlopen(3)`


### `option`

The option macro is used to write a command-line option which is
**defined in the same man page**.

Usage example: `option:--output`, `option:--verbose`


### `nloption`

Command-line option generating no link. This is used when writing
about an option which is **not defined in the same man page**.

Usage example: `nloption:-finstrument-functions`


### `not`

The `:not:` macro is used to emphasize on _not_.


Includes
--------

  * `common-authors.txt`: common authors section of the LTTng-UST
    project. Only use this for man pages which describe
    a command/library/function written by the main authors of LTTng-UST.
  * `common-copyright.txt`: common copyrights section of the LTTng-UST
    project. Only use this for man pages which describe
    a command/library/function having the common LTTng-UST license.
  * `common-footer.txt`: common footer for all man pages. This goes
    before the copyrights section.
  * `log-levels.txt`: definition list of LTTng-UST log levels.
  * `tracef-tracelog-limitations.txt`: limitations that apply to both
    the `lttng_ust_tracef(3)` and `lttng_ust_tracelog(3)` man pages.


Convention
----------

Please follow those rules when updating the current man pages or writing
new ones:

  * Always use macros when possible (man page references, command-line
    options, _not_, etc.).
  * Use callouts with the `term` role for command-line examples.
  * Use a verse, possibly with the `term` role, in the synopsis section.
  * Always refer to _long_ options in the text.
  * Use the `option:--option='PARAM'` format (with `=`) when providing a
    parameter to long options.
  * Prefer writing _user space_ rather than _userspace_, _user-space_,
    or _user land_.
  * Write _file system_, not _filesystem_.
  * Prefer writing _use case_ rather than _use-case_ or _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_).
  * Use an active voice, and prefer using the second person (_you_) when
    referring to the user.
  * Avoid using Latin abbreviations (_e.g._, _i.e._, _etc._).
Commit	Line	Data
4ddbd0b7 PP	1	LTTng-UST man pages
	2	===================
	3
	4	This directory contains the sources of the LTTng-UST man pages.
	5
	6	LTTng-UST 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 specify a reference to another man page.
	29	Using the provided `asciidoc.conf` configuration file, the man page
	30	name is rendered in bold and the section is normal.
	31
	32	Usage example: `man:lttng-enable-channel(1)`, `man:dlopen(3)`
	33
	34
	35	### `option`
	36
	37	The option macro is used to write a command-line option which is
	38	defined in the same man page.
	39
	40	Usage example: `option:--output`, `option:--verbose`
	41
	42
	43	### `nloption`
	44
	45	Command-line option generating no link. This is used when writing
	46	about an option which is not defined in the same man page.
	47
	48	Usage example: `nloption:-finstrument-functions`
	49
	50
	51	### `not`
	52
	53	The `:not:` macro is used to emphasize on _not_.
	54
	55
	56	Includes
	57	--------
	58
	59	* `common-authors.txt`: common authors section of the LTTng-UST
	60	project. Only use this for man pages which describe
	61	a command/library/function written by the main authors of LTTng-UST.
	62	* `common-copyright.txt`: common copyrights section of the LTTng-UST
	63	project. Only use this for man pages which describe
	64	a command/library/function having the common LTTng-UST license.
65	* `common-footer.txt`: common footer for all man pages. This goes
66	before the copyrights section.
67	* `log-levels.txt`: definition list of LTTng-UST log levels.
68	* `tracef-tracelog-limitations.txt`: limitations that apply to both
fb24f1b6	69	the `lttng_ust_tracef(3)` and `lttng_ust_tracelog(3)` man pages.
4ddbd0b7 PP	70
	71
	72	Convention
	73	----------
	74
	75	Please follow those rules when updating the current man pages or writing
	76	new ones:
	77
	78	* Always use macros when possible (man page references, command-line
	79	options, _not_, etc.).
	80	* Use callouts with the `term` role for command-line examples.
	81	* Use a verse, possibly with the `term` role, in the synopsis section.
	82	* Always refer to _long_ options in the text.
	83	* Use the `option:--option='PARAM'` format (with `=`) when providing a
	84	parameter to long options.
	85	* Prefer writing _user space_ rather than _userspace_, _user-space_,
	86	or _user land_.
	87	* Write _file system_, not _filesystem_.
	88	* Prefer writing _use case_ rather than _use-case_ or _usecase_.
	89	* Write _log level_, not _loglevel_.
	90	* Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_,
	91	and _LTTng-tools_, not _modules_, _UST_ and _tools_.
	92	* Prefer simple emphasis to strong emphasis for emphasizing text.
	93	* Try to stay behind the 72th column mark if possible, and behind the
	94	80th column otherwise.
	95	* Do not end directory paths with a forward slash (good:
	96	`include/trace/events`, bad: `include/trace/events/`).
	97	* Minimize the use of the future tense (_will_).
	98	* Use an active voice, and prefer using the second person (_you_) when
	99	referring to the user.
	100	* Avoid using Latin abbreviations (_e.g._, _i.e._, _etc._).