--- /dev/null
+= Babeltrace man pages
+Philippe Proulx
+4 October 2017
+
+This directory contains the sources of the Babeltrace man pages.
+
+The Babeltrace man pages are written in
+http://www.methods.co.nz/asciidoc/[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).
+
+
+== Naming
+
+Main program::
+ +__program__.1.txt+
+
+`babeltrace(1)` command::
+ +babeltrace-__command__.1.txt+
+
+Babeltrace introduction::
+ `babeltrace-intro.7.txt`
+
+Babeltrace plugin::
+ +babeltrace-plugin-__plugin__.7.txt+
+
+Babeltrace plugin's component class::
+ +babeltrace-__type__.__plugin__.__compcls__.7.txt+
+
+
+== Macros
+
+AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
+macro definitions used everywhere in the man page sources:
+
++man:__page__(__section__)+::
+ Use this macro to insert a link to another man page named
+ +__page__+ in section +__section__+. In troff, the man page's name
+ is rendered in bold.
++
+Example: `man:babeltrace-convert(1)`
+
++opt:__name__+::
+ Use this macro to insert a link to the command-line option
+ +__name__+ described in an _OPTIONS_ section in the same man page.
++
+Example: `opt:--verbose`, `opt:--color='WHEN'`
+
++manopt:__page__(__section__):__name__+::
+ Use this macro to insert a link to the command-line option
+ +__name__+ described in the _OPTIONS_ section of another Babeltrace
+ or LTTng man page named +__page__+ in section +__section__+.
++
+Example: `manopt:babeltrace(1):--log-level`,
++manopt:babeltrace-convert(1):--component=\`source.ctf.fs`+
+
++nlopt:__name__+::
+ Use this macro to write a command-line option named +__name__+
+ without inserting a link. The option does not need to be described
+ in the same man page.
++
+Example: `nlopt:--help`
+
++param:__name__+::
+ Use this macro to insert a link to the component initialization
+ parameter named +__name__+ described in an _INITIALIZATION
+ PARAMETERS_ section in the same man page.
++
+Example: `param:begin`, `param:path='PATH'`
+
++manparam:__type__.__plug__.__compclsname__:__paramname__+::
+ Use this macro to insert a link to the component initialization
+ parameter +__paramname__+ described in the _INITIALIZATION
+ PARAMETERS_ section of the man page of another Babeltrace component
+ class. The component class has the type +__type__+, is found in the
+ plugin named +__plug__+ and is named +__name__+.
++
+Example: `manparam:filter.utils.trimmer:begin`,
+`manparam:source.ctf.fs:path`
+
++nlparam:__name__+::
+ Use this macro to write a component initialization parameter named
+ +__name__+ without inserting a link. The parameter does not need to
+ be described in the same man page.
++
+Example: `nlparam:end`
+
++compcls:__type__.__plug__.__name__+::
+ Use this macro to write a component class specification. The
+ component class has the type +__type__+, is found in the plugin
+ named +__plug__+ and is named +__name__+.
++
+Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
+
+`:not:`::
+ Use `:not:` to emphasize _not_.
+
+`:escstar:`::
+ Use `:escstar:` to insert `\*` literally.
+
+`:esccomma:`::
+ Use `:esccomma:` to insert `\,` literally.
+
+`:escdot:`::
+ Use `:escdot:` to insert `\.` literally.
+
+
+== Attributes
+
+`manpagetype`::
+ Each man page must set this attribute to the type (lowercase) of the
+ man page: `program`, `command`, `plugin`, or `component class`. It's
+ used in various included files to output a text that is more
+ targeted.
+
+`revdate`::
+ Each man page should have its own revision date with the following
+ https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
+ _28 October 1987_.
++
+Make sure to update this date when you update a given man page. We are
+not generating the date automatically because we want the real last
+revision date in the man page, not the last build date.
+
+Also see `asciidoc-attrs.conf` which is generated by `config.status`
+from `asciidoc-attrs.conf.in`. This file contains fixed and
+configuration-dependent attributes which you can use anywhere in the
+sources.
+
+
+== Style
+
+Apply the recommendations of the
+link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style
+considerations_] section of the LTTng Documentation's contributor's
+guide.
projects / deliverable / babeltrace.git / blobdiff