= 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 "`<>`", 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 `—` 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 `—` 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 (`{nbsp}`, or HTML entity ` `) 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 +`+), 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 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 <>. 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 <>, 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()` ---- ====