doc/man/README.md

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