Skip to content

Latest commit

 

History

History
375 lines (296 loc) · 10.2 KB

CONTRIBUTING.adoc

File metadata and controls

375 lines (296 loc) · 10.2 KB

The LTTng Documentation: Contributor’s guide

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

The LTTng Documentation exists to make the 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 2.7) does its best to follow the rules of the 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 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 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:

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

    Example 1. Using the manual macro.
    See man:lttng-ust(3) to learn more about [...]

  • LTTng command-line option: Starting from LTTng 2.8, always use the opt:PAGE(SECTION):OPTION macro when you refer to a command-line option described in an LTTng manual page.

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

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

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

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

    Example 6. 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 — HTML entity twice.

Example 7. 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.
Example 8. Using — 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—__event record loss__ might be experienced.

Non-breaking space

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

Example 9. Using a non-breaking space between a quantity and its unit.
The size of this C{nbsp}source file is 1039{nbsp}bytes.
Example 10. 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 +`), and place `__ around the (preferably uppercase) placeholder.

Example 11. 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:

  • 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 “$ ” to indicate that a regular Unix user should run it. Start a command line with “# ” to indicate that the root Unix user should run it.

    Example 12. Using a terminal box.
    [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.

    Example 13. Using a source code box.
    [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 Pygments.

    Always indent source code examples with 4 spaces.

In any listing block, the lines must not exceed 80 characters (prefer a maximum of 72 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. Otherwise, use simple backticks.

  • Always follow the option name with the option word.

Example 14. 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 terminal box, always put = between the option name and its argument, if any.

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

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

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

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