doc/man/README.adoc

   1 = Babeltrace man pages
   2 Philippe Proulx
   3 4 October 2017
   4
   5 This directory contains the sources of the Babeltrace man pages.
   6
   7 The Babeltrace man pages are written in
   8 http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
   9 DocBook (XML) using the `asciidoc` command, and finally to troff using
  10 the appropriate DocBook XSL stylesheet (using the `xmlto` command).
  11
  12
  13 == Naming
  14
  15 Main program::
  16     +__program__.1.txt+
  17
  18 `babeltrace2(1)` command::
  19     +babeltrace2-__command__.1.txt+
  20
  21 Babeltrace introduction::
  22     `babeltrace2-intro.7.txt`
  23
  24 Babeltrace plugin::
  25     +babeltrace2-plugin-__plugin__.7.txt+
  26
  27 Babeltrace plugin's component class::
  28     +babeltrace2-__type__.__plugin__.__compcls__.7.txt+
  29
  30
  31 == Macros
  32
  33 AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
  34 macro definitions used everywhere in the man page sources:
  35
  36 +man:__page__(__section__)+::
  37     Use this macro to insert a link to another man page named
  38     +__page__+ in section +__section__+. In troff, the man page's name
  39     is rendered in bold.
  40 +
  41 Example: `man:babeltrace2-convert(1)`
  42
  43 +opt:__name__+::
  44     Use this macro to insert a link to the command-line option
  45     +__name__+ described in an _OPTIONS_ section in the same man page.
  46 +
  47 Example: `opt:--verbose`, `opt:--color='WHEN'`
  48
  49 +manopt:__page__(__section__):__name__+::
  50     Use this macro to insert a link to the command-line option
  51     +__name__+ described in the _OPTIONS_ section of another Babeltrace
  52     or LTTng man page named +__page__+ in section +__section__+.
  53 +
  54 Example: `manopt:babeltrace2(1):--log-level`,
  55 +manopt:babeltrace2-convert(1):--component=\`source.ctf.fs`+
  56
  57 +nlopt:__name__+::
  58     Use this macro to write a command-line option named +__name__+
  59     without inserting a link. The option does not need to be described
  60     in the same man page.
  61 +
  62 Example: `nlopt:--help`
  63
  64 +param:__name__+::
  65     Use this macro to insert a link to the component initialization
  66     parameter named +__name__+ described in an _INITIALIZATION
  67     PARAMETERS_ section in the same man page.
  68 +
  69 Example: `param:begin`, `param:path='PATH'`
  70
  71 +manparam:__type__.__plug__.__compclsname__:__paramname__+::
  72     Use this macro to insert a link to the component initialization
  73     parameter +__paramname__+ described in the _INITIALIZATION
  74     PARAMETERS_ section of the man page of another Babeltrace component
  75     class. The component class has the type +__type__+, is found in the
  76     plugin named +__plug__+ and is named +__name__+.
  77 +
  78 Example: `manparam:filter.utils.trimmer:begin`,
  79 `manparam:source.ctf.fs:path`
  80
  81 +nlparam:__name__+::
  82     Use this macro to write a component initialization parameter named
  83     +__name__+ without inserting a link. The parameter does not need to
  84     be described in the same man page.
  85 +
  86 Example: `nlparam:end`
  87
  88 +compcls:__type__.__plug__.__name__+::
  89     Use this macro to write a component class specification. The
  90     component class has the type +__type__+, is found in the plugin
  91     named +__plug__+ and is named +__name__+.
  92 +
  93 Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
  94
  95 `:not:`::
  96     Use `:not:` to emphasize _not_.
  97
  98 `:escstar:`::
  99     Use `:escstar:` to insert `\*` literally.
 100
 101 `:esccomma:`::
 102     Use `:esccomma:` to insert `\,` literally.
 103
 104 `:escdot:`::
 105     Use `:escdot:` to insert `\.` literally.
 106
 107
 108 == Attributes
 109
 110 `manpagetype`::
 111     Each man page must set this attribute to the type (lowercase) of the
 112     man page: `program`, `command`, `plugin`, or `component class`. It's
 113     used in various included files to output a text that is more
 114     targeted.
 115
 116 `revdate`::
 117     Each man page should have its own revision date with the following
 118     https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
 119     _28 October 1987_.
 120 +
 121 Make sure to update this date when you update a given man page. We are
 122 not generating the date automatically because we want the real last
 123 revision date in the man page, not the last build date.
 124
 125 Also see `asciidoc-attrs.conf` which is generated by `config.status`
 126 from `asciidoc-attrs.conf.in`. This file contains fixed and
 127 configuration-dependent attributes which you can use anywhere in the
 128 sources.
 129
 130
 131 == Style
 132
 133 Apply the recommendations of the
 134 link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style
 135 considerations_] section of the LTTng Documentation's contributor's
 136 guide.