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