| 1 | = The LTTng Documentation: Contributor's guide |
| 2 | Philippe Proulx |
| 3 | 14 June 2021 |
| 4 | |
| 5 | This guide presents the structure and conventions of the source of the |
| 6 | LTTng Documentation. Make sure you read it thoroughly before you |
| 7 | contribute a change. |
| 8 | |
| 9 | |
| 10 | [[principles]] |
| 11 | == Principles |
| 12 | |
| 13 | The LTTng Documentation exists to make the https://lttng.org/[LTTng |
| 14 | project] useable. Without such a complete documentation consolidating |
| 15 | the various concepts, features, and procedures of LTTng-tools, |
| 16 | LTTng-UST, and LTTng-modules, most of the project would only be useable |
| 17 | by its authors. |
| 18 | |
| 19 | Why not simply read the manual pages? While the LTTng manual pages are |
| 20 | complementary to the LTTng Documentation, they remain formal references: |
| 21 | they lack the introductory quality and many procedural user guides found |
| 22 | in this documentation. |
| 23 | |
| 24 | The core principle of the LTTng Documentation is to make the text as |
| 25 | cleverly organized, easy to follow, precise, and consistent as possible. |
| 26 | This involves keeping a high level of rigor to such things as the style, |
| 27 | voice, grammar, and layout of the document. |
| 28 | |
| 29 | Of course, those guidelines are not new to the technical writing realm, |
| 30 | and it would be bold to devise a brand new manual of style for the sole |
| 31 | existence of the LTTng Documentation when so many have already proven |
| 32 | their value. This is why the LTTng Documentation (especially starting |
| 33 | from version{nbsp}2.7) does its best to follow the rules of the |
| 34 | https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual |
| 35 | of Style (4th edition)], a landmark work in its field. Of particular |
| 36 | interest in this book are: |
| 37 | |
| 38 | * Chapter 1: _Microsoft style and voice_. |
| 39 | * Chapter 6: _Procedures and technical content_. |
| 40 | * Chapter 7: _Practical issues of style_. |
| 41 | * Chapter 8: _Grammar_. |
| 42 | * Chapter 9: _Punctuation_. |
| 43 | * Chapter 11: _Acronyms and other abbreviations_. |
| 44 | |
| 45 | |
| 46 | == Organization of the repository and format |
| 47 | |
| 48 | The Git repository of the LTTng Documentation contains all the official |
| 49 | versions of the documentation as separate source files. Each source file |
| 50 | is in its own `2.__x__` directory, along with documentation resources |
| 51 | specific to this version of LTTng. The `common` directory contains |
| 52 | common source files. |
| 53 | |
| 54 | The source files are written in |
| 55 | http://www.methods.co.nz/asciidoc/[AsciiDoc] (the original, Python |
| 56 | version), a rich, lightweight markup language with all the blocks and |
| 57 | inline elements needed to write backend-agnostic content. |
| 58 | |
| 59 | Although the official LTTng website uses a custom script to generate its |
| 60 | own HTML version of the LTTng Documentation, you can generate a |
| 61 | self-contained HTML preview (see link:README.adoc[`README.adoc`]). The |
| 62 | `asciidoc.html5.conf` AsciiDoc configuration file sets a few attributes |
| 63 | and implements the required macros for this preview target. |
| 64 | |
| 65 | |
| 66 | == Validation script |
| 67 | |
| 68 | Before you submit any change, make sure that the check script passes. |
| 69 | This is a Python script which validates some elements of a specific |
| 70 | document. |
| 71 | |
| 72 | You need the following dependencies to run the check script: |
| 73 | |
| 74 | * http://www.methods.co.nz/asciidoc/[AsciiDoc] |
| 75 | * Python 3 |
| 76 | * http://lxml.de/[lxml] Python 3 package |
| 77 | * https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package |
| 78 | |
| 79 | Run the check script: |
| 80 | |
| 81 | ---- |
| 82 | $ python3 tools/check.py 2.12/lttng-docs-2.12.txt |
| 83 | ---- |
| 84 | |
| 85 | Replace `__2.12__` with the version of the document to validate. |
| 86 | |
| 87 | |
| 88 | == Style considerations |
| 89 | |
| 90 | As stated in "`<<principles,Principles>>`", the LTTng Documentation |
| 91 | follows the Microsoft Manual of Style (4th edition). We encourage you to |
| 92 | read this work before you contribute a major change to the document. |
| 93 | |
| 94 | You also need to consider the following rules, often specific to the |
| 95 | AsciiDoc format used to write the LTTng Documentation, when you edit |
| 96 | existing content or when you create new sections. |
| 97 | |
| 98 | |
| 99 | === Macros |
| 100 | |
| 101 | * **Manual page reference**: Always use the |
| 102 | `man:__PAGE__(__SECTION__)` macro when you refer to a manual page. |
| 103 | + |
| 104 | .Using the `manual` macro. |
| 105 | ==== |
| 106 | ---- |
| 107 | See man:lttng-ust(3) to learn more about [...] |
| 108 | ---- |
| 109 | ==== |
| 110 | |
| 111 | * [[opt-macro]] **LTTng command-line option**: Starting from |
| 112 | LTTng{nbsp}2.8, always use the `opt:__PAGE__(__SECTION__):__OPTION__` |
| 113 | macro when you refer to a command-line option described in an LTTng |
| 114 | manual page. |
| 115 | + |
| 116 | .Using the `opt` macro. |
| 117 | ==== |
| 118 | ---- |
| 119 | Use the opt:lttng-enable-event(1):--filter option to set the |
| 120 | filter expression of a recording event rule. |
| 121 | ---- |
| 122 | ==== |
| 123 | |
| 124 | * **File name**: Always use the `path:{__PATH__}` macro when you need |
| 125 | to write a file name. |
| 126 | + |
| 127 | .Using the `path` macro. |
| 128 | ==== |
| 129 | ---- |
| 130 | Load the configuration file path:{hello.lttng} directory by default. |
| 131 | ---- |
| 132 | ==== |
| 133 | |
| 134 | * **Directory name**: Always use the `dir:{__PATH__}` macro when you |
| 135 | need to write a directory name. |
| 136 | + |
| 137 | .Using the `dir` macro. |
| 138 | ==== |
| 139 | ---- |
| 140 | Traces are recorded to the dir:{~/lttng-traces} directory by default. |
| 141 | ---- |
| 142 | ==== |
| 143 | |
| 144 | * **Environment variable**: Always use the `env:__VAR__` macro when you |
| 145 | need to write an environment variable name. `__VAR__` must _not_ |
| 146 | contain the `$` shell prefix. |
| 147 | + |
| 148 | .Using the `env` macro. |
| 149 | ==== |
| 150 | ---- |
| 151 | Set the env:LTTNG_UST_DEBUG environment variable to `1` to activate the |
| 152 | debug mode of LTTng-UST. |
| 153 | ---- |
| 154 | ==== |
| 155 | |
| 156 | * **Command name**: Always use the `cmd:__COMMAND__` macro when you |
| 157 | need to write a command name. |
| 158 | + |
| 159 | .Using the `cmd` macro. |
| 160 | ==== |
| 161 | ---- |
| 162 | Run cmd:lttng-sessiond as the `root` Unix user. |
| 163 | ---- |
| 164 | ==== |
| 165 | |
| 166 | |
| 167 | === Dash |
| 168 | |
| 169 | You can usually write an em dash with `--` in AsciiDoc, but sometimes |
| 170 | the AsciiDoc processor keeps them as is, for example if the character at |
| 171 | the left or at the right of them is a punctuation. In this case, use the |
| 172 | equivalent `—` HTML entity twice. |
| 173 | |
| 174 | .Using `--` for an em dash. |
| 175 | ==== |
| 176 | ---- |
| 177 | And yet, when the car was finally delivered--nearly three months after |
| 178 | it was ordered--she decided she no longer wanted it, leaving the dealer |
| 179 | with an oddly equipped car that would be difficult to sell. |
| 180 | ---- |
| 181 | ==== |
| 182 | |
| 183 | .Using `—` for an em dash. |
| 184 | ==== |
| 185 | ---- |
| 186 | As the frequency of recorded events increases--either because the event |
| 187 | throughput is actually higher or because you enabled more recording |
| 188 | event rules than usual—__event record loss__ might be experienced. |
| 189 | ---- |
| 190 | ==== |
| 191 | |
| 192 | |
| 193 | === Non-breaking space |
| 194 | |
| 195 | Always use a non-breaking space (`{nbsp}`, or HTML entity ` `) |
| 196 | between a quantity and its unit, or when it would be unnatural to have |
| 197 | two related words split on two lines. |
| 198 | |
| 199 | .Using a non-breaking space between a quantity and its unit. |
| 200 | ==== |
| 201 | ---- |
| 202 | The size of this C{nbsp}source file is 1039{nbsp}bytes. |
| 203 | ---- |
| 204 | ==== |
| 205 | |
| 206 | .Using a non-breaking space to avoid an odd line break. |
| 207 | ==== |
| 208 | ---- |
| 209 | This integer is displayed in base{nbsp}16. |
| 210 | ---- |
| 211 | ==== |
| 212 | |
| 213 | |
| 214 | === Placeholder in inline code |
| 215 | |
| 216 | When a section of an inline code element is a placeholder, or variable, |
| 217 | use the ``+`` form of the element (instead of +`+), and place `__` |
| 218 | around the (preferably uppercase) placeholder. |
| 219 | |
| 220 | .Using a placeholder in an inline code element. |
| 221 | ==== |
| 222 | ---- |
| 223 | Name your file +something.__SYS__.c+, where +__SYS__+ is the name of |
| 224 | your system. |
| 225 | ---- |
| 226 | ==== |
| 227 | |
| 228 | |
| 229 | === Listing block |
| 230 | |
| 231 | There are two types of listing blocks: |
| 232 | |
| 233 | * [[term-box]]A **terminal box** shows commands to be entered in a |
| 234 | terminal exclusively. In other words, you must _not_ write the output |
| 235 | of commands in a terminal box. |
| 236 | + |
| 237 | A terminal box is an AsciiDoc literal block with the `term` role. |
| 238 | + |
| 239 | Start a command line with "```${nbsp}```" to indicate that a regular |
| 240 | Unix user should run it. Start a command line with "```#{nbsp}```" to |
| 241 | indicate that the `root` Unix user should run it. |
| 242 | + |
| 243 | .Using a terminal box. |
| 244 | ==== |
| 245 | [listing] |
| 246 | .... |
| 247 | [role="term"] |
| 248 | ---- |
| 249 | $ lttng create my-session |
| 250 | $ lttng enable-event --kernel --all |
| 251 | ---- |
| 252 | .... |
| 253 | ==== |
| 254 | + |
| 255 | Write the output of a command line with a simple, role-less listing |
| 256 | block. |
| 257 | |
| 258 | * A **source code box** shows syntax-highlighted snippets of |
| 259 | source code. |
| 260 | + |
| 261 | A source code box is an AsciiDoc source code block. |
| 262 | + |
| 263 | .Using a source code box. |
| 264 | ==== |
| 265 | [listing] |
| 266 | .... |
| 267 | [source,c] |
| 268 | ---- |
| 269 | #include <stdio.h> |
| 270 | |
| 271 | int main(void) |
| 272 | { |
| 273 | puts("Hello, World!"); |
| 274 | return 0; |
| 275 | } |
| 276 | ---- |
| 277 | .... |
| 278 | ==== |
| 279 | + |
| 280 | The second attribute is the name of the programming language for |
| 281 | proper syntax highlighting (for example, `c`, `python`, `make`, `java`). |
| 282 | This name must be known to http://pygments.org/[Pygments]. |
| 283 | + |
| 284 | Always indent source code examples with 4{nbsp}spaces. |
| 285 | |
| 286 | In any listing block, the lines must not exceed 80 characters (prefer a |
| 287 | maximum of 72{nbsp}characters). |
| 288 | |
| 289 | |
| 290 | === Command-line option |
| 291 | |
| 292 | When you specify a command-line option: |
| 293 | |
| 294 | * Always use the long form of the option (with two hyphens). |
| 295 | |
| 296 | * **If the command which accepts this option is an LTTng program**, |
| 297 | use the <<opt-macro,`opt` macro>>. Otherwise, use simple backticks. |
| 298 | |
| 299 | * Always follow the option name with the _option_ word. |
| 300 | |
| 301 | .Using a command-line option. |
| 302 | ==== |
| 303 | ---- |
| 304 | You can use the opt:lttng(1):--group option of the cmd:lttng tool to |
| 305 | specify your custom tracing group. |
| 306 | ---- |
| 307 | ==== |
| 308 | |
| 309 | In a <<term-box,terminal box>>, always put `=` between the option name |
| 310 | and its argument, if any. |
| 311 | |
| 312 | .Terminal box. |
| 313 | ==== |
| 314 | In this example, `provider:'sys_*'` is not the argument of the |
| 315 | `--userspace` option: it's the first non-option argument, and the |
| 316 | `--userspace` option has no arguments. |
| 317 | |
| 318 | [listing] |
| 319 | .... |
| 320 | [role="term"] |
| 321 | ---- |
| 322 | $ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \ |
| 323 | --exclude=sys_send,sys_block --loglevel=INFO |
| 324 | ---- |
| 325 | .... |
| 326 | ==== |
| 327 | |
| 328 | |
| 329 | === Procedure |
| 330 | |
| 331 | Use an ordered list to write a procedure. |
| 332 | |
| 333 | If a step is optional, prepend `+**Optional**:+` followed with a space |
| 334 | to the first sentence of the step. |
| 335 | |
| 336 | Start the first sentence with a capital letter. |
| 337 | |
| 338 | Don't use an optional step followed with a condition; use a conditional |
| 339 | step for this. |
| 340 | |
| 341 | If a step is conditional, put the condition (_If something_) in bold, |
| 342 | followed with a comma, followed with the step itself. |
| 343 | |
| 344 | |
| 345 | === External link |
| 346 | |
| 347 | When using a hyperlink to a file/directory of an LTTng repository, link |
| 348 | to the GitHub code browser. Make sure to link to the appropriate Git |
| 349 | branch (usually `stable-2.__x__`). You can use the `revision` AsciiDoc |
| 350 | attribute in the URL. |
| 351 | |
| 352 | .Link to source file. |
| 353 | ==== |
| 354 | ---- |
| 355 | See the file |
| 356 | https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}] |
| 357 | for more details about [...] |
| 358 | ---- |
| 359 | ==== |
| 360 | |
| 361 | |
| 362 | === "`Since`" sections |
| 363 | |
| 364 | If a whole section describes a feature which was introduced in LTTng 2.1 |
| 365 | or later, assign the `since-2.__x__` role to the section, where `__x__` |
| 366 | is the minor version of the LTTng release which introduced the feature. |
| 367 | |
| 368 | .Section heading describing a feature introduced in LTTng 2.5. |
| 369 | ==== |
| 370 | ---- |
| 371 | [role="since-2.5"] |
| 372 | [[tracef]] |
| 373 | ==== Use `lttng_ust_tracef()` |
| 374 | ---- |
| 375 | ==== |