Merge "2.13: Cleanup duplicate paragraph"

[lttng-docs.git] / CONTRIBUTING.adoc

= The LTTng Documentation: Contributor's guide
Philippe Proulx
14 June 2021

This guide presents the structure and conventions of the source of the
LTTng Documentation. Make sure you read it thoroughly before you
contribute a change.


[[principles]]
== Principles

The LTTng Documentation exists to make the https://lttng.org/[LTTng
project] useable. Without such a complete documentation consolidating
the various concepts, features, and procedures of LTTng-tools,
LTTng-UST, and LTTng-modules, most of the project would only be useable
by its authors.

Why not simply read the manual pages? While the LTTng manual pages are
complementary to the LTTng Documentation, they remain formal references:
they lack the introductory quality and many procedural user guides found
in this documentation.

The core principle of the LTTng Documentation is to make the text as
cleverly organized, easy to follow, precise, and consistent as possible.
This involves keeping a high level of rigor to such things as the style,
voice, grammar, and layout of the document.

Of course, those guidelines are not new to the technical writing realm,
and it would be bold to devise a brand new manual of style for the sole
existence of the LTTng Documentation when so many have already proven
their value. This is why the LTTng Documentation (especially starting
from version{nbsp}2.7) does its best to follow the rules of the
https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual
of Style (4th edition)], a landmark work in its field. Of particular
interest in this book are:

* Chapter 1: _Microsoft style and voice_.
* Chapter 6: _Procedures and technical content_.
* Chapter 7: _Practical issues of style_.
* Chapter 8: _Grammar_.
* Chapter 9: _Punctuation_.
* Chapter 11: _Acronyms and other abbreviations_.


== Organization of the repository and format

The Git repository of the LTTng Documentation contains all the official
versions of the documentation as separate source files. Each source file
is in its own `2.__x__` directory, along with documentation resources
specific to this version of LTTng. The `common` directory contains
common source files.

The source files are written in
http://www.methods.co.nz/asciidoc/[AsciiDoc] (the original, Python
version), a rich, lightweight markup language with all the blocks and
inline elements needed to write backend-agnostic content.

Although the official LTTng website uses a custom script to generate its
own HTML version of the LTTng Documentation, you can generate a
self-contained HTML preview (see link:README.adoc[`README.adoc`]). The
`asciidoc.html5.conf` AsciiDoc configuration file sets a few attributes
and implements the required macros for this preview target.


== Validation script

Before you submit any change, make sure that the check script passes.
This is a Python script which validates some elements of a specific
document.

You need the following dependencies to run the check script:

* http://www.methods.co.nz/asciidoc/[AsciiDoc]
* Python 3
* http://lxml.de/[lxml] Python 3 package
* https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package

Run the check script:

----
$ python3 tools/check.py 2.12/lttng-docs-2.12.txt
----

Replace `__2.12__` with the version of the document to validate.


== Style considerations

As stated in "`<<principles,Principles>>`", the LTTng Documentation
follows the Microsoft Manual of Style (4th edition). We encourage you to
read this work before you contribute a major change to the document.

You also need to consider the following rules, often specific to the
AsciiDoc format used to write the LTTng Documentation, when you edit
existing content or when you create new sections.


=== Macros

* **Manual page reference**: Always use the
  `man:__PAGE__(__SECTION__)` macro when you refer to a manual page.
+
.Using the `manual` macro.
====
----
See man:lttng-ust(3) to learn more about [...]
----
====

* [[opt-macro]] **LTTng command-line option**: Starting from
  LTTng{nbsp}2.8, always use the `opt:__PAGE__(__SECTION__):__OPTION__`
  macro when you refer to a command-line option described in an LTTng
  manual page.
+
.Using the `opt` macro.
====
----
Use the opt:lttng-enable-event(1):--filter option to set the
filter expression of a recording event rule.
----
====

* **File name**: Always use the `path:{__PATH__}` macro when you need
  to write a file name.
+
.Using the `path` macro.
====
----
Load the configuration file path:{hello.lttng} directory by default.
----
====

* **Directory name**: Always use the `dir:{__PATH__}` macro when you
  need to write a directory name.
+
.Using the `dir` macro.
====
----
Traces are recorded to the dir:{~/lttng-traces} directory by default.
----
====

* **Environment variable**: Always use the `env:__VAR__` macro when you
  need to write an environment variable name. `__VAR__` must _not_
  contain the `$` shell prefix.
+
.Using the `env` macro.
====
----
Set the env:LTTNG_UST_DEBUG environment variable to `1` to activate the
debug mode of LTTng-UST.
----
====

* **Command name**: Always use the `cmd:__COMMAND__` macro when you
  need to write a command name.
+
.Using the `cmd` macro.
====
----
Run cmd:lttng-sessiond as the `root` Unix user.
----
====


=== Dash

You can usually write an em dash with `--` in AsciiDoc, but sometimes
the AsciiDoc processor keeps them as is, for example if the character at
the left or at the right of them is a punctuation. In this case, use the
equivalent `&#8212;` HTML entity twice.

.Using `--` for an em dash.
====
----
And yet, when the car was finally delivered--nearly three months after
it was ordered--she decided she no longer wanted it, leaving the dealer
with an oddly equipped car that would be difficult to sell.
----
====

.Using `&#8212;` for an em dash.
====
----
As the frequency of recorded events increases--either because the event
throughput is actually higher or because you enabled more recording
event rules than usual&#8212;__event record loss__ might be experienced.
----
====


=== Non-breaking space

Always use a non-breaking space (`{nbsp}`, or HTML entity `&#160;`)
between a quantity and its unit, or when it would be unnatural to have
two related words split on two lines.

.Using a non-breaking space between a quantity and its unit.
====
----
The size of this C{nbsp}source file is 1039{nbsp}bytes.
----
====

.Using a non-breaking space to avoid an odd line break.
====
----
This integer is displayed in base{nbsp}16.
----
====


=== Placeholder in inline code

When a section of an inline code element is a placeholder, or variable,
use the ``+`` form of the element (instead of +&#96;+), and place `__`
around the (preferably uppercase) placeholder.

.Using a placeholder in an inline code element.
====
----
Name your file +something.__SYS__.c+, where +__SYS__+ is the name of
your system.
----
====


=== Listing block

There are two types of listing blocks:

* [[term-box]]A **terminal box** shows commands to be entered in a
  terminal exclusively. In other words, you must _not_ write the output
  of commands in a terminal box.
+
A terminal box is an AsciiDoc literal block with the `term` role.
+
Start a command line with "```${nbsp}```" to indicate that a regular
Unix user should run it. Start a command line with "```#{nbsp}```" to
indicate that the `root` Unix user should run it.
+
.Using a terminal box.
====
[listing]
....
[role="term"]
----
$ lttng create my-session
$ lttng enable-event --kernel --all
----
....
====
+
Write the output of a command line with a simple, role-less listing
block.

* A **source code box**  shows syntax-highlighted snippets of
  source code.
+
A source code box is an AsciiDoc source code block.
+
.Using a source code box.
====
[listing]
....
[source,c]
----
#include <stdio.h>

int main(void)
{
    puts("Hello, World!");
    return 0;
}
----
....
====
+
The second attribute is the name of the programming language for
proper syntax highlighting (for example, `c`, `python`, `make`, `java`).
This name must be known to http://pygments.org/[Pygments].
+
Always indent source code examples with 4{nbsp}spaces.

In any listing block, the lines must not exceed 80 characters (prefer a
maximum of 72{nbsp}characters).


=== Command-line option

When you specify a command-line option:

* Always use the long form of the option (with two hyphens).

* **If the command which accepts this option is an LTTng program**,
  use the <<opt-macro,`opt` macro>>. Otherwise, use simple backticks.

* Always follow the option name with the _option_ word.

.Using a command-line option.
====
----
You can use the opt:lttng(1):--group option of the cmd:lttng tool to
specify your custom tracing group.
----
====

In a <<term-box,terminal box>>, always put `=` between the option name
and its argument, if any.

.Terminal box.
====
In this example, `provider:'sys_*'` is not the argument of the
`--userspace` option: it's the first non-option argument, and the
`--userspace` option has no arguments.

[listing]
....
[role="term"]
----
$ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \
                     --exclude=sys_send,sys_block --loglevel=INFO
----
....
====


=== Procedure

Use an ordered list to write a procedure.

If a step is optional, prepend `+**Optional**:+` followed with a space
to the first sentence of the step.

Start the first sentence with a capital letter.

Don't use an optional step followed with a condition; use a conditional
step for this.

If a step is conditional, put the condition (_If something_) in bold,
followed with a comma, followed with the step itself.


=== External link

When using a hyperlink to a file/directory of an LTTng repository, link
to the GitHub code browser. Make sure to link to the appropriate Git
branch (usually `stable-2.__x__`). You can use the `revision` AsciiDoc
attribute in the URL.

.Link to source file.
====
----
See the file
https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}]
for more details about [...]
----
====


=== "`Since`" sections

If a whole section describes a feature which was introduced in LTTng 2.1
or later, assign the `since-2.__x__` role to the section, where `__x__`
is the minor version of the LTTng release which introduced the feature.

.Section heading describing a feature introduced in LTTng 2.5.
====
----
[role="since-2.5"]
[[tracef]]
==== Use `lttng_ust_tracef()`
----
====