CONTRIBUTING.adoc

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