doc/man/README.md

   1 <!--
   2 SPDX-FileCopyrightText: 2016 Philippe Proulx <pproulx@efficios.com>
   3
   4 SPDX-License-Identifier: CC-BY-4.0
   5 -->
   6
   7 LTTng-UST man pages
   8 ===================
   9
  10 This directory contains the sources of the LTTng-UST man pages.
  11
  12 LTTng-UST man pages are written in
  13 [AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to
  14 DocBook (XML) using the `asciidoc` command, and finally to troff using
  15 the appropriate DocBook XSL stylesheet (using the `xmlto` command).
  16
  17
  18 Custom XSL stylesheets
  19 ----------------------
  20
  21 There are a few custom XSL stylesheets applied for customizing the
  22 generated man pages in the `xsl` directory.
  23
  24
  25 Macros
  26 ------
  27
  28 AsciiDoc is configured with `asciidoc.conf` which contains a few
  29 macro definitions used everywhere in the man page sources.
  30
  31
  32 ### `man`
  33
  34 The `man` macro is used to specify a reference to another man page.
  35 Using the provided `asciidoc.conf` configuration file, the man page
  36 name is rendered in bold and the section is normal.
  37
  38 Usage example: `man:lttng-enable-channel(1)`, `man:dlopen(3)`
  39
  40
  41 ### `option`
  42
  43 The option macro is used to write a command-line option which is
  44 **defined in the same man page**.
  45
  46 Usage example: `option:--output`, `option:--verbose`
  47
  48
  49 ### `nloption`
  50
  51 Command-line option generating no link. This is used when writing
  52 about an option which is **not defined in the same man page**.
  53
  54 Usage example: `nloption:-finstrument-functions`
  55
  56
  57 ### `not`
  58
  59 The `:not:` macro is used to emphasize on _not_.
  60
  61
  62 Includes
  63 --------
  64
  65   * `common-authors.txt`: common authors section of the LTTng-UST
  66     project. Only use this for man pages which describe
  67     a command/library/function written by the main authors of LTTng-UST.
  68   * `common-copyright.txt`: common copyrights section of the LTTng-UST
  69     project. Only use this for man pages which describe
  70     a command/library/function having the common LTTng-UST license.
  71   * `common-footer.txt`: common footer for all man pages. This goes
  72     before the copyrights section.
  73   * `log-levels.txt`: definition list of LTTng-UST log levels.
  74   * `tracef-tracelog-limitations.txt`: limitations that apply to both
  75     the `lttng_ust_tracef(3)` and `lttng_ust_tracelog(3)` man pages.
  76
  77
  78 Convention
  79 ----------
  80
  81 Please follow those rules when updating the current man pages or writing
  82 new ones:
  83
  84   * Always use macros when possible (man page references, command-line
  85     options, _not_, etc.).
  86   * Use callouts with the `term` role for command-line examples.
  87   * Use a verse, possibly with the `term` role, in the synopsis section.
  88   * Always refer to _long_ options in the text.
  89   * Use the `option:--option='PARAM'` format (with `=`) when providing a
  90     parameter to long options.
  91   * Prefer writing _user space_ rather than _userspace_, _user-space_,
  92     or _user land_.
  93   * Write _file system_, not _filesystem_.
  94   * Prefer writing _use case_ rather than _use-case_ or _usecase_.
  95   * Write _log level_, not _loglevel_.
  96   * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_,
  97     and _LTTng-tools_, not _modules_, _UST_ and _tools_.
  98   * Prefer simple emphasis to strong emphasis for emphasizing text.
  99   * Try to stay behind the 72th column mark if possible, and behind the
 100     80th column otherwise.
 101   * Do not end directory paths with a forward slash (good:
 102     `include/trace/events`, bad: `include/trace/events/`).
 103   * Minimize the use of the future tense (_will_).
 104   * Use an active voice, and prefer using the second person (_you_) when
 105     referring to the user.
 106   * Avoid using Latin abbreviations (_e.g._, _i.e._, _etc._).