| 1 | The LTTng Documentation: Contributor's guide |
| 2 | ============================================ |
| 3 | Philippe Proulx |
| 4 | v1.0, 26 October 2016 |
| 5 | |
| 6 | This guide presents the structure and conventions of the LTTng |
| 7 | Documentation's source. Make sure you read it thoroughly before |
| 8 | you contribute a change. |
| 9 | |
| 10 | |
| 11 | [[principles]] |
| 12 | == Principles |
| 13 | |
| 14 | The LTTng Documentation exists to make the |
| 15 | https://lttng.org/[LTTng project] useable. |
| 16 | Without such a complete documentation consolidating the various |
| 17 | concepts, features, and procedures of LTTng-tools, LTTng-UST, and |
| 18 | LTTng-modules, most of the project would only be useable by |
| 19 | its authors. |
| 20 | |
| 21 | Why not simply read the man pages? While the LTTng man pages are |
| 22 | complementary to the LTTng Documentation, they remain formal |
| 23 | references: they lack the introductory quality and procedural user |
| 24 | guides found in this documentation. |
| 25 | |
| 26 | The core principle of the LTTng Documentation is to make the text as |
| 27 | cleverly organized, easy to follow, precise, and consistent as possible. |
| 28 | This involves keeping a high level of rigor as to such things as the |
| 29 | document's style, voice, grammar, and layout. |
| 30 | |
| 31 | Of course, those guidelines are not new to the technical writing realm, |
| 32 | and it would be bold to devise a brand new manual of style for the sole |
| 33 | existence of the LTTng Documentation when so many have already proven |
| 34 | their value. This is why the LTTng Documentation (especially starting |
| 35 | from version 2.7) does its best to follow the rules of the |
| 36 | https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual |
| 37 | of Style (4th edition)], a landmark work in its field. Of particular |
| 38 | interest in this book are: |
| 39 | |
| 40 | * Chapter 1, _Microsoft style and voice_. |
| 41 | * Chapter 6, _Procedures and technical content_. |
| 42 | * Chapter 7, _Practical issues of style_. |
| 43 | * Chapter 8, _Grammar_. |
| 44 | * Chapter 9, _Punctuation_. |
| 45 | * Chapter 11, _Acronyms and other abbreviations_. |
| 46 | |
| 47 | The <<terminology,Terminology>> section of this contributor's guide |
| 48 | adds terms to or overrides terms of Part 2, _Usage Dictionary_. |
| 49 | |
| 50 | |
| 51 | == Organization of the repository and format |
| 52 | |
| 53 | The Git repository of the LTTng Documentation contains all the official |
| 54 | versions of the documentation as separate source files. Each source file |
| 55 | is in its own +2.__x__+ directory, along with documentation resources |
| 56 | specific to this version of LTTng. You can find common source files in |
| 57 | the `common` directory. |
| 58 | |
| 59 | The source files are written in |
| 60 | http://www.methods.co.nz/asciidoc/[AsciiDoc], a rich, lightweight markup |
| 61 | language with all the blocks and inline elements needed to write |
| 62 | backend-agnostic content. |
| 63 | |
| 64 | Although the official LTTng website uses a custom script to generate |
| 65 | its own HTML version of the LTTng Documentation, it is possible to |
| 66 | generate an autonomous HTML preview (see |
| 67 | link:README.adoc[`README.adoc`]). The `asciidoc.html5.conf` AsciiDoc |
| 68 | configuration file sets a few attributes and implements the required |
| 69 | macros for this preview target. |
| 70 | |
| 71 | |
| 72 | == Validation script |
| 73 | |
| 74 | Before you submit any change, make sure that the check script passes. |
| 75 | This is a Python script which validates some elements of a specific |
| 76 | document. |
| 77 | |
| 78 | You need the following dependencies to run the check script: |
| 79 | |
| 80 | * http://www.methods.co.nz/asciidoc/[AsciiDoc] |
| 81 | * Python 3 |
| 82 | * http://lxml.de/[lxml] Python 3 package |
| 83 | * https://pypi.python.org/pypi/termcolor[termcolor] Python 3 package |
| 84 | |
| 85 | Run the check script: |
| 86 | |
| 87 | ---- |
| 88 | python3 tools/check.py 2.7/lttng-docs-2.7.txt |
| 89 | ---- |
| 90 | |
| 91 | Replace `2.7` by the version of the document to validate in the previous |
| 92 | command line. |
| 93 | |
| 94 | |
| 95 | == Style considerations |
| 96 | |
| 97 | As stated in <<principles,Principles>>, the LTTng Documentation follows |
| 98 | the Microsoft Manual of Style (4th edition). We encourage you to read |
| 99 | this work before contributing a major change to the document. |
| 100 | |
| 101 | You also need to consider the following rules, often specific to the |
| 102 | AsciiDoc format used to write the LTTng Documentation, when you edit |
| 103 | existing content or when you create new sections. |
| 104 | |
| 105 | |
| 106 | === Macros |
| 107 | |
| 108 | * **Man page references**: Always use the +man:__command__(__section__)+ |
| 109 | macro when you refer to a man page. |
| 110 | + |
| 111 | .Using the `man` macro. |
| 112 | ==== |
| 113 | ---- |
| 114 | See man:lttng-ust(3) for more details about ... |
| 115 | ---- |
| 116 | ==== |
| 117 | |
| 118 | * [[opt-macro]] **LTTng command-line options**: Starting from v2.8, |
| 119 | always use the +opt:__command__(__section__):__option__+ macro when |
| 120 | you refer to a command-line option described in an LTTng man page. |
| 121 | + |
| 122 | .Using the `opt` macro. |
| 123 | ==== |
| 124 | ---- |
| 125 | You can use the opt:lttng-enable-event(1):--filter option to set the |
| 126 | filter expression of an event rule. |
| 127 | ---- |
| 128 | ==== |
| 129 | |
| 130 | * **File names**: Always use the +path:{__path__}+ macro when you need |
| 131 | to write a file name. |
| 132 | + |
| 133 | .Using the `path` macro. |
| 134 | ==== |
| 135 | ---- |
| 136 | Load the configuration file path:{hello.lttng} directory by default. |
| 137 | ---- |
| 138 | ==== |
| 139 | |
| 140 | * **Directory names**: Always use the +dir:{__path__}+ macro when you |
| 141 | need to write a directory name. |
| 142 | + |
| 143 | .Using the `dir` macro. |
| 144 | ==== |
| 145 | ---- |
| 146 | Traces are recorded to the dir:{~/lttng-traces} directory by default. |
| 147 | ---- |
| 148 | ==== |
| 149 | |
| 150 | * **Environment variable**: Always use the +env:__VAR__+ macro when you |
| 151 | need to write an environment variable name. +__VAR__+ must not contain |
| 152 | the shell's `$` prefix. |
| 153 | + |
| 154 | .Using the `env` macro. |
| 155 | ==== |
| 156 | ---- |
| 157 | You can set the env:LTTNG_UST_DEBUG environment variable to `1` to |
| 158 | activate LTTng-UST's debug output. |
| 159 | ---- |
| 160 | ==== |
| 161 | |
| 162 | * **Command names**: Always use the +cmd:__cmd__+ macro when you need to |
| 163 | write a command name. |
| 164 | + |
| 165 | .Using the `cmd` macro. |
| 166 | ==== |
| 167 | ---- |
| 168 | Run cmd:lttng-sessiond as the root user. |
| 169 | ---- |
| 170 | ==== |
| 171 | |
| 172 | |
| 173 | === Dashes |
| 174 | |
| 175 | Em dashes can usually be written using `--` in AsciiDoc, but sometimes |
| 176 | the two hyphens are outputted as is, for example if the character at the |
| 177 | left or at the right of them is a punctuation. You can avoid this |
| 178 | by using the equivalent `—` HTML entity. |
| 179 | |
| 180 | .Using `--` for an em dash. |
| 181 | ==== |
| 182 | ---- |
| 183 | And yet, when the car was finally delivered--nearly three months after it |
| 184 | was ordered--she decided she no longer wanted it, leaving the dealer with |
| 185 | an oddly equipped car that would be difficult to sell. |
| 186 | ---- |
| 187 | ==== |
| 188 | |
| 189 | .Using `—` for an em dash. |
| 190 | ==== |
| 191 | ---- |
| 192 | As the frequency of recorded events increases--either because the event |
| 193 | throughput is actually higher or because you enabled more events than |
| 194 | usual—__event loss__ might be experienced. |
| 195 | ---- |
| 196 | ==== |
| 197 | |
| 198 | |
| 199 | === Non-breaking spaces |
| 200 | |
| 201 | Always use a non-breaking space (`{nbsp}`, or HTML entity ` `) |
| 202 | between a quantity and its unit, or when it would be unnatural to have |
| 203 | two related words split on two lines. |
| 204 | |
| 205 | .Using a non-breaking space between a quantity and its unit. |
| 206 | ==== |
| 207 | ---- |
| 208 | The size of this file is 1039{nbsp}bytes. |
| 209 | ---- |
| 210 | ==== |
| 211 | |
| 212 | .Using a non-breaking space to avoid an odd line break. |
| 213 | ==== |
| 214 | ---- |
| 215 | This integer is displayed in base{nbsp}16. |
| 216 | ---- |
| 217 | ==== |
| 218 | |
| 219 | |
| 220 | === Placeholders in inline code |
| 221 | |
| 222 | When a section of an inline code element is a placeholder, or variable, |
| 223 | use the `+` form of the element (instead of +`+), and place `__` |
| 224 | around the placeholder. |
| 225 | |
| 226 | .Using a placeholder in an inline code element. |
| 227 | ==== |
| 228 | ---- |
| 229 | Name your file +something.__sys__.c+, where +__sys__+ is your system name. |
| 230 | ---- |
| 231 | ==== |
| 232 | |
| 233 | |
| 234 | === Listing blocks |
| 235 | |
| 236 | There are two types of listing blocks: |
| 237 | |
| 238 | * [[term-box]]**Terminal boxes** are used to show commands to be entered in a |
| 239 | terminal exclusively, that is, the output of commands must not be |
| 240 | written in terminal boxes. A terminal box is an AsciiDoc literal |
| 241 | block with the `term` role. |
| 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 | The output of a command line can be written using a simple, role-less |
| 256 | listing block. |
| 257 | |
| 258 | * **Source code boxes** are used to show syntax-highlighted snippets of |
| 259 | source code. A source code box is an AsciiDoc source code block. |
| 260 | + |
| 261 | .Using a source code box. |
| 262 | ==== |
| 263 | [listing] |
| 264 | .... |
| 265 | [source,c] |
| 266 | ---- |
| 267 | #include <stdio.h> |
| 268 | |
| 269 | int main(void) |
| 270 | { |
| 271 | puts("Hello, World!"); |
| 272 | |
| 273 | return 0; |
| 274 | } |
| 275 | ---- |
| 276 | .... |
| 277 | ==== |
| 278 | + |
| 279 | The second attribute is the name of the programming language for |
| 280 | proper syntax highlighting (for example, `c`, `python`, `make`, `java`). |
| 281 | This name must be known to http://pygments.org/[Pygments]. |
| 282 | + |
| 283 | Always indent source code examples with 4{nbsp}spaces. |
| 284 | |
| 285 | In any listing block, the lines must not exceed 80 characters (prefer a |
| 286 | maximum of 72 characters). |
| 287 | |
| 288 | |
| 289 | === Command-line options |
| 290 | |
| 291 | When specifying command-line options: |
| 292 | |
| 293 | * Always use the long form of the option (with two hyphens). |
| 294 | * **If the command which accepts this option is an LTTng program**, |
| 295 | use the <<opt-macro,`opt` macro>>. Otherwise use simple backticks. |
| 296 | * Always follow the option name by the _option_ word. |
| 297 | |
| 298 | .Using a command-line option. |
| 299 | ==== |
| 300 | ---- |
| 301 | You can use the `lttng` tool's opt:lttng(1):--group option to specify a |
| 302 | custom tracing group. |
| 303 | ---- |
| 304 | ==== |
| 305 | |
| 306 | In <<term-box,terminal boxes>>, always put `=` between the option name |
| 307 | and its argument, if any. |
| 308 | |
| 309 | .Terminal box. |
| 310 | ==== |
| 311 | In this example, `provider:'sys_*'` is not the argument of the |
| 312 | `--userspace` option: it's the first positional argument, and |
| 313 | the `--userspace` option has no arguments. |
| 314 | |
| 315 | [listing] |
| 316 | .... |
| 317 | [role="term"] |
| 318 | ---- |
| 319 | lttng enable-event --userspace provider:'sys_*' --filter='field < 23' |
| 320 | --exclude=sys_send,sys_block --loglevel=TRACE_INFO |
| 321 | ---- |
| 322 | .... |
| 323 | ==== |
| 324 | |
| 325 | |
| 326 | === Procedures |
| 327 | |
| 328 | Use an ordered list to write a procedure. |
| 329 | |
| 330 | If a step is optional, prepend `**Optional**:` followed by a space to |
| 331 | the step's first sentence. Start the first sentence with a capital |
| 332 | letter. Do not use an optional step followed by a condition; use a |
| 333 | conditional step for this. |
| 334 | |
| 335 | If a step is conditional, put the condition (_If something_) in bold, |
| 336 | followed by a comma, followed by the step itself. |
| 337 | |
| 338 | |
| 339 | === External links |
| 340 | |
| 341 | When using a hyperlink to an LTTng repository's file or directory, |
| 342 | link to the GitHub code browser. Make sure to link to the appropriate |
| 343 | Git branch (usually +stable-2.__x__+). You can use the `revision` |
| 344 | attribute in the URL. |
| 345 | |
| 346 | .Link to source file. |
| 347 | ==== |
| 348 | ---- |
| 349 | See the file |
| 350 | https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}] |
| 351 | for more details about [...] |
| 352 | ---- |
| 353 | ==== |
| 354 | |
| 355 | |
| 356 | === "Since" sections |
| 357 | |
| 358 | If a whole section describes a feature which was introduced in LTTng 2.1 |
| 359 | or later, add the +since-2.__x__+ role to the section's heading, where |
| 360 | +__x__+ is the minor version of the LTTng release which introduced |
| 361 | the feature. |
| 362 | |
| 363 | .Section heading describing a feature introduced in LTTng 2.5. |
| 364 | ==== |
| 365 | ---- |
| 366 | [role="since-2.5"] |
| 367 | [[tracef]] |
| 368 | ==== Use `tracef()` |
| 369 | ---- |
| 370 | ==== |
| 371 | |
| 372 | |
| 373 | [[terminology]] |
| 374 | == Terminology |
| 375 | |
| 376 | What follows is an official, partial list of technical terms used by the |
| 377 | LTTng Documentation. Other forms of those terms are _not_ permitted. For |
| 378 | example, do not write `use-case` or `filesystem`. |
| 379 | |
| 380 | Autotools:: |
| 381 | The GNU Autotools. |
| 382 | + |
| 383 | Do not use _autotools_. |
| 384 | |
| 385 | Babeltrace:: |
| 386 | The Babeltrace project, which includes the `babeltrace` command, some |
| 387 | libraries, and Python bindings. |
| 388 | + |
| 389 | Use +`babeltrace`+ to refer to the actual `babeltrace` command. |
| 390 | |
| 391 | Babeltrace Python bindings:: |
| 392 | The Python bindings of Babeltrace. |
| 393 | + |
| 394 | The plural _bindings_ is important. |
| 395 | |
| 396 | Bash:: |
| 397 | The Bash shell. |
| 398 | + |
| 399 | Do not use _bash_. |
| 400 | |
| 401 | buffering scheme:: |
| 402 | A layout of tracing buffers applied to a given channel. |
| 403 | |
| 404 | channel:: |
| 405 | An LTTng channel. |
| 406 | |
| 407 | CLI:: |
| 408 | Prefer expanding this acronym to _command-line interface_ in the text. |
| 409 | |
| 410 | clock:: |
| 411 | A reference of time for a tracer. |
| 412 | + |
| 413 | Use _system time_ to refer to the date and time as seen by a user. |
| 414 | |
| 415 | command-line:: |
| 416 | Adjective version of _command line_: _command-line option_, |
| 417 | _command-line interface_. |
| 418 | |
| 419 | command-line interface:: |
| 420 | An interface in which the user enters command lines to instruct the |
| 421 | system what to do. |
| 422 | + |
| 423 | Prefer using _command_ or _command-line tool_ to refer to a |
| 424 | specific command. |
| 425 | |
| 426 | command line:: |
| 427 | An actual line of command entered by the user in a terminal, at a |
| 428 | command prompt. |
| 429 | + |
| 430 | Write _command-line_ when used as an adjective. |
| 431 | |
| 432 | consumer daemon:: |
| 433 | The LTTng consumer daemon. |
| 434 | + |
| 435 | Do not use _consumerd_. |
| 436 | + |
| 437 | Use +`lttng-consumerd`+ to refer to the consumer daemon |
| 438 | executable. |
| 439 | |
| 440 | domain:: |
| 441 | Do not use when referring to a _tracing domain_. |
| 442 | |
| 443 | event:: |
| 444 | Occurrence recognised by software, emitted by a tracer when specific |
| 445 | conditions are met, at a given time. An event _occurs_ at a specific |
| 446 | time, after which a tracer can record its payload. |
| 447 | |
| 448 | event loss mode:: |
| 449 | The mechanism by which event records of a given channel are lost |
| 450 | (not recorded) when there is no sub-buffer space left to store them. |
| 451 | |
| 452 | event name:: |
| 453 | The name of an event, which is also the name of the event record. |
| 454 | This is different from a _tracepoint name_, which is only the name |
| 455 | of the instrumentation point, not necessarily equal to the event |
| 456 | name. |
| 457 | |
| 458 | event record:: |
| 459 | Record, in a trace, of the payload of an event which occured. |
| 460 | |
| 461 | event rule:: |
| 462 | Set of conditions which must be satisfied for one or more events |
| 463 | to occur. The `lttng enable-event` command creates and enables |
| 464 | _event rules_, not _events_. |
| 465 | |
| 466 | file system:: |
| 467 | Contains directories, files, and links in an organized structure. |
| 468 | + |
| 469 | Do not use _filesystem_ or _file-system_. |
| 470 | |
| 471 | +`java.util.logging`+:: |
| 472 | Even though the `--jul` command-line option is an acronym for this |
| 473 | term, there is no such thing as _Java Util Logging_. The only |
| 474 | correct form is the name of the Java package, |
| 475 | +`java.util.logging`+. |
| 476 | |
| 477 | instrumentation:: |
| 478 | The use of LTTng probes to make a software traceable. |
| 479 | |
| 480 | libc:: |
| 481 | Do not use. |
| 482 | + |
| 483 | Use _the C standard library_ to refer to the standard library for |
| 484 | the C programming language, or _glibc_ to refer to the GNU C Library |
| 485 | specifically. |
| 486 | |
| 487 | log4j:: |
| 488 | LTTng-UST supports Java logging using Apache _log4j_, not Apache |
| 489 | Log4j 2. |
| 490 | |
| 491 | log level:: |
| 492 | Level of severity of a log statement. |
| 493 | + |
| 494 | Do not hyphenate. |
| 495 | |
| 496 | kernel:: |
| 497 | In general, do not use _kernel_ to refer to the _Linux kernel_: use |
| 498 | the whole _Linux kernel_ term, because other operating system kernels |
| 499 | exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng |
| 500 | kernel modules_. |
| 501 | |
| 502 | Linux Trace Toolkit: next generation:: |
| 503 | The expansion of the _LTTng_ acronym. |
| 504 | + |
| 505 | The colon and the lowercase _n_ and _g_ are important. |
| 506 | |
| 507 | LTTng-analyses:: |
| 508 | The LTTng-analyses project. |
| 509 | |
| 510 | LTTng-modules:: |
| 511 | The LTTng-modules project. |
| 512 | |
| 513 | LTTng-tools:: |
| 514 | The LTTng-tools project. |
| 515 | |
| 516 | LTTng-UST:: |
| 517 | The LTTng-UST project. |
| 518 | |
| 519 | LTTng-UST Java agent:: |
| 520 | LTTng-UST Python agent:: |
| 521 | An LTTng user space agent. |
| 522 | + |
| 523 | Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_. |
| 524 | |
| 525 | LTTng Documentation:: |
| 526 | The name of this project. |
| 527 | + |
| 528 | Do not use _LTTng documentation_. |
| 529 | + |
| 530 | When referring to the project, the _the_ determiner can be lowercase: |
| 531 | _Welcome to the LTTng Documentation!_. |
| 532 | |
| 533 | LTTng live:: |
| 534 | The name of a communication protocol between Babeltrace and the |
| 535 | relay daemon which makes it possible to see events "live", |
| 536 | as they are received by the relay daemon. |
| 537 | + |
| 538 | Do not hyphenate. |
| 539 | |
| 540 | the +`lttng`+ tool:: |
| 541 | the +`lttng`+ command line tool:: |
| 542 | The `lttng` command line tool. |
| 543 | + |
| 544 | When _tool_ has been mentioned in the previous sentences, you can use |
| 545 | +`lttng`+ alone. |
| 546 | |
| 547 | Makefile:: |
| 548 | An input for the make tool. |
| 549 | + |
| 550 | Do not use _makefile_ or _make file_. |
| 551 | |
| 552 | man page:: |
| 553 | Unix-style reference manual page. |
| 554 | + |
| 555 | Do not hyphenate. |
| 556 | |
| 557 | per-process buffering:: |
| 558 | A buffering scheme in which each process has its own buffer for a |
| 559 | given user space channel. |
| 560 | + |
| 561 | Do not use _per-PID buffering_. |
| 562 | |
| 563 | per-user buffering:: |
| 564 | A buffering scheme in which all the processes of a user share the same |
| 565 | buffer for a given user space channel. |
| 566 | + |
| 567 | Do not use _per-UID buffering_. |
| 568 | |
| 569 | probe:: |
| 570 | An instrumentation point. |
| 571 | + |
| 572 | Prefer _tracepoint_ when referring to a user space or Linux kernel |
| 573 | LTTng tracepoint. |
| 574 | |
| 575 | real-time clock:: |
| 576 | A clock which keeps track of the current time, including eventual |
| 577 | time corrections. |
| 578 | + |
| 579 | Do not use _realtime clock_ or _real time clock_. |
| 580 | |
| 581 | relay daemon:: |
| 582 | The LTTng relay daemon. |
| 583 | + |
| 584 | Do not use _relayd_. |
| 585 | + |
| 586 | Use +`lttng-relayd`+ to refer to the relay daemon executable. |
| 587 | |
| 588 | root user:: |
| 589 | A superuser of a Linux system. |
| 590 | + |
| 591 | Do not use +`root`+. |
| 592 | |
| 593 | session:: |
| 594 | Do not use when referring to a _tracing session_. |
| 595 | |
| 596 | session daemon:: |
| 597 | The LTTng session daemon. |
| 598 | + |
| 599 | Do not use _sessiond_. |
| 600 | + |
| 601 | Use +`lttng-sessiond`+ to refer to the session daemon |
| 602 | executable. |
| 603 | |
| 604 | snapshot:: |
| 605 | Copy of the current data of all the buffers of a given tracing |
| 606 | session, saved as a trace. |
| 607 | |
| 608 | sub-buffer:: |
| 609 | One part of an LTTng ring buffer. |
| 610 | + |
| 611 | Do not use _subbuffer_ since it's harder to read with the two |
| 612 | contiguous b's. |
| 613 | |
| 614 | timestamp:: |
| 615 | Time information attached to an event when it is emitted. This is not |
| 616 | necessarily a _Unix timestamp_. |
| 617 | + |
| 618 | Do not use _time stamp_. |
| 619 | |
| 620 | trace:: |
| 621 | As a verb: a user or a tracer can _trace_ an application. |
| 622 | |
| 623 | Trace Compass:: |
| 624 | The Trace Compass project and application. |
| 625 | + |
| 626 | Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or |
| 627 | _Tracecompass_. |
| 628 | |
| 629 | tracepoint:: |
| 630 | An instrumentation point using the tracepoint mechanism of |
| 631 | the Linux kernel or of LTTng-UST. |
| 632 | + |
| 633 | Do not use _trace point_ or _trace-point_. |
| 634 | |
| 635 | tracepoint definition:: |
| 636 | The definition of a single tracepoint. |
| 637 | |
| 638 | tracepoint name:: |
| 639 | The name of a _tracepoint_. |
| 640 | + |
| 641 | Not to be confused with an _event name_. |
| 642 | |
| 643 | tracepoint provider:: |
| 644 | A set of functions providing tracepoints to an instrumented user |
| 645 | application. |
| 646 | + |
| 647 | Not to be confused with a _tracepoint provider package_: many tracepoint |
| 648 | providers can exist within a tracepoint provider package. |
| 649 | |
| 650 | tracepoint provider package:: |
| 651 | One or more tracepoint providers compiled as an object file or as |
| 652 | a shared library. |
| 653 | |
| 654 | tracing domain:: |
| 655 | An LTTng tracing domain. |
| 656 | + |
| 657 | Always use the complete _tracing domain_ term, not _domain_ alone, |
| 658 | unless _tracing domain_ has been used in the few preceding sentences. |
| 659 | |
| 660 | tracing group:: |
| 661 | The Unix group in which a user can be to be allowed to trace the |
| 662 | Linux kernel. |
| 663 | + |
| 664 | Do not use _`tracing` group_, as the name of the tracing |
| 665 | group is configurable. |
| 666 | |
| 667 | tracing session:: |
| 668 | An LTTng tracing session. |
| 669 | + |
| 670 | Always use the complete _tracing session_ term, not _session_ alone. |
| 671 | |
| 672 | Unix:: |
| 673 | Unix operating system or philosophy. |
| 674 | + |
| 675 | Do not use _UNIX_. |
| 676 | |
| 677 | Unix epoch:: |
| 678 | Absolute reference of a real-time clock. |
| 679 | + |
| 680 | Use the term as a proper noun: do not precede it with _the_. |
| 681 | + |
| 682 | Do not use _Epoch_ alone. |
| 683 | |
| 684 | Unix timestamp:: |
| 685 | Timestamp represented as the number of seconds since Unix epoch. |
| 686 | |
| 687 | use case:: |
| 688 | According to Wikipedia: List of actions or event steps, typically |
| 689 | defining the interactions between a role and a system, to |
| 690 | achieve a goal. |
| 691 | + |
| 692 | Do not hyphenate. |
| 693 | |
| 694 | user application:: |
| 695 | An application running in user space, as opposed to a Linux kernel |
| 696 | module, for example. |
| 697 | + |
| 698 | Do not use _user space application_, as this is redundant. |
| 699 | |
| 700 | user space:: |
| 701 | User processes. |
| 702 | + |
| 703 | Do not hyphenate. |