CONTRIBUTING.adoc

   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 `&#8212;` 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 `&#8212;` 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&#8212;__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 `&#160;`)
 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 +&#96;+), 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 Start a command line with "+${nbsp}+" to indicate that a regular Unix user
 244 should run it. Start a command line with "+#{nbsp}+" to indicate that a
 245 priviledged Unix user should run it.
 246 +
 247 .Using a terminal box.
 248 ====
 249 [listing]
 250 ....
 251 [role="term"]
 252 ----
 253 $ lttng create my-session
 254 $ lttng enable-event --kernel --all
 255 ----
 256 ....
 257 ====
 258 +
 259 The output of a command line can be written using a simple, role-less
 260 listing block.
 261
 262 * **Source code boxes** are used to show syntax-highlighted snippets of
 263   source code. A source code box is an AsciiDoc source code block.
 264 +
 265 .Using a source code box.
 266 ====
 267 [listing]
 268 ....
 269 [source,c]
 270 ----
 271 #include <stdio.h>
 272
 273 int main(void)
 274 {
 275     puts("Hello, World!");
 276
 277     return 0;
 278 }
 279 ----
 280 ....
 281 ====
 282 +
 283 The second attribute is the name of the programming language for
 284 proper syntax highlighting (for example, `c`, `python`, `make`, `java`).
 285 This name must be known to http://pygments.org/[Pygments].
 286 +
 287 Always indent source code examples with 4{nbsp}spaces.
 288
 289 In any listing block, the lines must not exceed 80 characters (prefer a
 290 maximum of 72 characters).
 291
 292
 293 === Command-line options
 294
 295 When specifying command-line options:
 296
 297 * Always use the long form of the option (with two hyphens).
 298 * **If the command which accepts this option is an LTTng program**,
 299   use the <<opt-macro,`opt` macro>>. Otherwise use simple backticks.
 300 * Always follow the option name by the _option_ word.
 301
 302 .Using a command-line option.
 303 ====
 304 ----
 305 You can use the `lttng` tool's opt:lttng(1):--group option to specify a
 306 custom tracing group.
 307 ----
 308 ====
 309
 310 In <<term-box,terminal boxes>>, always put `=` between the option name
 311 and its argument, if any.
 312
 313 .Terminal box.
 314 ====
 315 In this example, `provider:'sys_*'` is not the argument of the
 316 `--userspace` option: it's the first positional argument, and
 317 the `--userspace` option has no arguments.
 318
 319 [listing]
 320 ....
 321 [role="term"]
 322 ----
 323 $ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \
 324                    --exclude=sys_send,sys_block --loglevel=TRACE_INFO
 325 ----
 326 ....
 327 ====
 328
 329
 330 === Procedures
 331
 332 Use an ordered list to write a procedure.
 333
 334 If a step is optional, prepend `**Optional**:` followed by a space to
 335 the step's first sentence. Start the first sentence with a capital
 336 letter. Do not use an optional step followed by a condition; use a
 337 conditional step for this.
 338
 339 If a step is conditional, put the condition (_If something_) in bold,
 340 followed by a comma, followed by the step itself.
 341
 342
 343 === External links
 344
 345 When using a hyperlink to an LTTng repository's file or directory,
 346 link to the GitHub code browser. Make sure to link to the appropriate
 347 Git branch (usually +stable-2.__x__+). You can use the `revision`
 348 attribute in the URL.
 349
 350 .Link to source file.
 351 ====
 352 ----
 353 See the file
 354 https://github.com/lttng/lttng-tools/blob/stable-{revision}/src/common/daemonize.c[path:{src/common/daemonize.c}]
 355 for more details about [...]
 356 ----
 357 ====
 358
 359
 360 === "Since" sections
 361
 362 If a whole section describes a feature which was introduced in LTTng 2.1
 363 or later, add the +since-2.__x__+ role to the section's heading, where
 364 +__x__+ is the minor version of the LTTng release which introduced
 365 the feature.
 366
 367 .Section heading describing a feature introduced in LTTng 2.5.
 368 ====
 369 ----
 370 [role="since-2.5"]
 371 [[tracef]]
 372 ==== Use `tracef()`
 373 ----
 374 ====
 375
 376
 377 [[terminology]]
 378 == Terminology
 379
 380 What follows is an official, partial list of technical terms used by the
 381 LTTng Documentation. Other forms of those terms are _not_ permitted. For
 382 example, do not write `use-case` or `filesystem`.
 383
 384 Autotools::
 385   The GNU Autotools.
 386 +
 387 Do not use _autotools_.
 388
 389 Babeltrace::
 390   The Babeltrace project, which includes the `babeltrace` command, some
 391   libraries, and Python bindings.
 392 +
 393 Use +&#96;babeltrace&#96;+ to refer to the actual `babeltrace` command.
 394
 395 Babeltrace Python bindings::
 396   The Python bindings of Babeltrace.
 397 +
 398 The plural _bindings_ is important.
 399
 400 Bash::
 401   The Bash shell.
 402 +
 403 Do not use _bash_.
 404
 405 buffering scheme::
 406   A layout of tracing buffers applied to a given channel.
 407
 408 channel::
 409   An LTTng channel.
 410
 411 CLI::
 412   Prefer expanding this acronym to _command-line interface_ in the text.
 413
 414 clock::
 415   A reference of time for a tracer.
 416 +
 417 Use _system time_ to refer to the date and time as seen by a user.
 418
 419 command-line::
 420   Adjective version of _command line_: _command-line option_,
 421   _command-line interface_.
 422
 423 command-line interface::
 424   An interface in which the user enters command lines to instruct the
 425   system what to do.
 426 +
 427 Prefer using _command_ or _command-line tool_ to refer to a
 428 specific command.
 429
 430 command line::
 431   An actual line of command entered by the user in a terminal, at a
 432   command prompt.
 433 +
 434 Write _command-line_ when used as an adjective.
 435
 436 consumer daemon::
 437   The LTTng consumer daemon.
 438 +
 439 Do not use _consumerd_.
 440 +
 441 Use +&#96;lttng-consumerd&#96;+ to refer to the consumer daemon
 442 executable.
 443
 444 domain::
 445   Do not use when referring to a _tracing domain_.
 446
 447 event::
 448   Occurrence recognised by software, emitted by a tracer when specific
 449   conditions are met, at a given time. An event _occurs_ at a specific
 450   time, after which a tracer can record its payload.
 451
 452 event loss mode::
 453   The mechanism by which event records of a given channel are lost
 454   (not recorded) when there is no sub-buffer space left to store them.
 455
 456 event name::
 457   The name of an event, which is also the name of the event record.
 458   This is different from a _tracepoint name_, which is only the name
 459   of the instrumentation point, not necessarily equal to the event
 460   name.
 461
 462 event record::
 463   Record, in a trace, of the payload of an event which occured.
 464
 465 event rule::
 466   Set of conditions which must be satisfied for one or more events
 467   to occur. The `lttng enable-event` command creates and enables
 468   _event rules_, not _events_.
 469
 470 file system::
 471   Contains directories, files, and links in an organized structure.
 472 +
 473 Do not use _filesystem_ or _file-system_.
 474
 475 +&#96;java.util.logging&#96;+::
 476   Even though the `--jul` command-line option is an acronym for this
 477   term, there is no such thing as _Java Util Logging_. The only
 478   correct form is the name of the Java package,
 479   +&#96;java.util.logging&#96;+.
 480
 481 instrumentation::
 482   The use of LTTng probes to make a software traceable.
 483
 484 libc::
 485   Do not use.
 486 +
 487 Use _the C standard library_ to refer to the standard library for
 488 the C programming language, or _glibc_ to refer to the GNU C Library
 489 specifically.
 490
 491 log4j::
 492   LTTng-UST supports Java logging using Apache _log4j_, not Apache
 493   Log4j 2.
 494
 495 log level::
 496   Level of severity of a log statement.
 497 +
 498 Do not hyphenate.
 499
 500 kernel::
 501   In general, do not use _kernel_ to refer to the _Linux kernel_: use
 502   the whole _Linux kernel_ term, because other operating system kernels
 503   exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng
 504   kernel modules_.
 505
 506 Linux Trace Toolkit: next generation::
 507   The expansion of the _LTTng_ acronym.
 508 +
 509 The colon and the lowercase _n_ and _g_ are important.
 510
 511 LTTng-analyses::
 512   The LTTng-analyses project.
 513
 514 LTTng-modules::
 515   The LTTng-modules project.
 516
 517 LTTng-tools::
 518   The LTTng-tools project.
 519
 520 LTTng-UST::
 521   The LTTng-UST project.
 522
 523 LTTng-UST Java agent::
 524 LTTng-UST Python agent::
 525   An LTTng user space agent.
 526 +
 527 Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_.
 528
 529 LTTng Documentation::
 530   The name of this project.
 531 +
 532 Do not use _LTTng documentation_.
 533 +
 534 When referring to the project, the _the_ determiner can be lowercase:
 535 _Welcome to the LTTng Documentation!_.
 536
 537 LTTng live::
 538   The name of a communication protocol between Babeltrace and the
 539   relay daemon which makes it possible to see events "live",
 540   as they are received by the relay daemon.
 541 +
 542 Do not hyphenate.
 543
 544 the +&#96;lttng&#96;+ tool::
 545 the +&#96;lttng&#96;+ command line tool::
 546   The `lttng` command line tool.
 547 +
 548 When _tool_ has been mentioned in the previous sentences, you can use
 549 +&#96;lttng&#96;+ alone.
 550
 551 Makefile::
 552   An input for the make tool.
 553 +
 554 Do not use _makefile_ or _make file_.
 555
 556 man page::
 557   Unix-style reference manual page.
 558 +
 559 Do not hyphenate.
 560
 561 per-process buffering::
 562   A buffering scheme in which each process has its own buffer for a
 563   given user space channel.
 564 +
 565 Do not use _per-PID buffering_.
 566
 567 per-user buffering::
 568   A buffering scheme in which all the processes of a user share the same
 569   buffer for a given user space channel.
 570 +
 571 Do not use _per-UID buffering_.
 572
 573 probe::
 574   An instrumentation point.
 575 +
 576 Prefer _tracepoint_ when referring to a user space or Linux kernel
 577 LTTng tracepoint.
 578
 579 real-time clock::
 580   A clock which keeps track of the current time, including eventual
 581   time corrections.
 582 +
 583 Do not use _realtime clock_ or _real time clock_.
 584
 585 relay daemon::
 586   The LTTng relay daemon.
 587 +
 588 Do not use _relayd_.
 589 +
 590 Use +&#96;lttng-relayd&#96;+ to refer to the relay daemon executable.
 591
 592 root user::
 593   A superuser of a Linux system.
 594 +
 595 Do not use +&#96;root&#96;+.
 596
 597 session::
 598   Do not use when referring to a _tracing session_.
 599
 600 session daemon::
 601   The LTTng session daemon.
 602 +
 603 Do not use _sessiond_.
 604 +
 605 Use +&#96;lttng-sessiond&#96;+ to refer to the session daemon
 606 executable.
 607
 608 snapshot::
 609   Copy of the current data of all the buffers of a given tracing
 610   session, saved as a trace.
 611
 612 sub-buffer::
 613   One part of an LTTng ring buffer.
 614 +
 615 Do not use _subbuffer_ since it's harder to read with the two
 616 contiguous b's.
 617
 618 timestamp::
 619   Time information attached to an event when it is emitted. This is not
 620   necessarily a _Unix timestamp_.
 621 +
 622 Do not use _time stamp_.
 623
 624 trace::
 625   As a verb: a user or a tracer can _trace_ an application.
 626
 627 Trace Compass::
 628   The Trace Compass project and application.
 629 +
 630 Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or
 631 _Tracecompass_.
 632
 633 tracepoint::
 634   An instrumentation point using the tracepoint mechanism of
 635   the Linux kernel or of LTTng-UST.
 636 +
 637 Do not use _trace point_ or _trace-point_.
 638
 639 tracepoint definition::
 640   The definition of a single tracepoint.
 641
 642 tracepoint name::
 643   The name of a _tracepoint_.
 644 +
 645 Not to be confused with an _event name_.
 646
 647 tracepoint provider::
 648   A set of functions providing tracepoints to an instrumented user
 649   application.
 650 +
 651 Not to be confused with a _tracepoint provider package_: many tracepoint
 652 providers can exist within a tracepoint provider package.
 653
 654 tracepoint provider package::
 655   One or more tracepoint providers compiled as an object file or as
 656   a shared library.
 657
 658 tracing domain::
 659   An LTTng tracing domain.
 660 +
 661 Always use the complete _tracing domain_ term, not _domain_ alone,
 662 unless _tracing domain_ has been used in the few preceding sentences.
 663
 664 tracing group::
 665   The Unix group in which a user can be to be allowed to trace the
 666   Linux kernel.
 667 +
 668 Do not use _&#96;tracing&#96; group_, as the name of the tracing
 669 group is configurable.
 670
 671 tracing session::
 672   An LTTng tracing session.
 673 +
 674 Always use the complete _tracing session_ term, not _session_ alone.
 675
 676 Unix::
 677   Unix operating system or philosophy.
 678 +
 679 Do not use _UNIX_.
 680
 681 Unix epoch::
 682   Absolute reference of a real-time clock.
 683 +
 684 Use the term as a proper noun: do not precede it with _the_.
 685 +
 686 Do not use _Epoch_ alone.
 687
 688 Unix timestamp::
 689   Timestamp represented as the number of seconds since Unix epoch.
 690
 691 use case::
 692   According to Wikipedia: List of actions or event steps, typically
 693   defining the interactions between a role and a system, to
 694   achieve a goal.
 695 +
 696 Do not hyphenate.
 697
 698 user application::
 699   An application running in user space, as opposed to a Linux kernel
 700   module, for example.
 701 +
 702 Do not use _user space application_, as this is redundant.
 703
 704 user space::
 705   User processes.
 706 +
 707 Do not hyphenate.