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 .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 +&#96;babeltrace&#96;+ 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 +&#96;lttng-consumerd&#96;+ 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 +&#96;java.util.logging&#96;+::
 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   +&#96;java.util.logging&#96;+.
 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 +&#96;lttng&#96;+ tool::
 541 the +&#96;lttng&#96;+ command line tool::
 542   The `lttng` command line tool.
 543 +
 544 When _tool_ has been mentioned in the previous sentences, you can use
 545 +&#96;lttng&#96;+ 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 +&#96;lttng-relayd&#96;+ to refer to the relay daemon executable.
 587
 588 root user::
 589   A superuser of a Linux system.
 590 +
 591 Do not use +&#96;root&#96;+.
 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 +&#96;lttng-sessiond&#96;+ 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 _&#96;tracing&#96; 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.