From 81f5f33d13fffde7d1163aa73f1d214f22c86153 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 14 Jun 2021 12:41:15 -0400 Subject: [PATCH] Update CONTRIBUTING.adoc Signed-off-by: Philippe Proulx --- CONTRIBUTING.adoc | 574 ++++++++++------------------------------------ 1 file changed, 121 insertions(+), 453 deletions(-) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 5077670..03aa8d0 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,72 +1,66 @@ -The LTTng Documentation: Contributor's guide -============================================ += The LTTng Documentation: Contributor's guide Philippe Proulx -v1.0, 26 October 2016 +14 June 2021 -This guide presents the structure and conventions of the LTTng -Documentation's source. Make sure you read it thoroughly before -you contribute a change. +This guide presents the structure and conventions of the source of the +LTTng Documentation. Make sure you read it thoroughly before you +contribute a change. [[principles]] == Principles -The LTTng Documentation exists to make the -https://lttng.org/[LTTng project] useable. -Without such a complete documentation consolidating the various -concepts, features, and procedures of LTTng-tools, LTTng-UST, and -LTTng-modules, most of the project would only be useable by -its authors. +The LTTng Documentation exists to make the https://lttng.org/[LTTng +project] useable. Without such a complete documentation consolidating +the various concepts, features, and procedures of LTTng-tools, +LTTng-UST, and LTTng-modules, most of the project would only be useable +by its authors. -Why not simply read the man pages? While the LTTng man pages are -complementary to the LTTng Documentation, they remain formal -references: they lack the introductory quality and procedural user -guides found in this documentation. +Why not simply read the manual pages? While the LTTng manual pages are +complementary to the LTTng Documentation, they remain formal references: +they lack the introductory quality and many procedural user guides found +in this documentation. The core principle of the LTTng Documentation is to make the text as cleverly organized, easy to follow, precise, and consistent as possible. -This involves keeping a high level of rigor as to such things as the -document's style, voice, grammar, and layout. +This involves keeping a high level of rigor to such things as the style, +voice, grammar, and layout of the document. Of course, those guidelines are not new to the technical writing realm, and it would be bold to devise a brand new manual of style for the sole existence of the LTTng Documentation when so many have already proven their value. This is why the LTTng Documentation (especially starting -from version 2.7) does its best to follow the rules of the +from version{nbsp}2.7) does its best to follow the rules of the https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual of Style (4th edition)], a landmark work in its field. Of particular interest in this book are: -* Chapter 1, _Microsoft style and voice_. -* Chapter 6, _Procedures and technical content_. -* Chapter 7, _Practical issues of style_. -* Chapter 8, _Grammar_. -* Chapter 9, _Punctuation_. -* Chapter 11, _Acronyms and other abbreviations_. - -The <> section of this contributor's guide -adds terms to or overrides terms of Part 2, _Usage Dictionary_. +* Chapter 1: _Microsoft style and voice_. +* Chapter 6: _Procedures and technical content_. +* Chapter 7: _Practical issues of style_. +* Chapter 8: _Grammar_. +* Chapter 9: _Punctuation_. +* Chapter 11: _Acronyms and other abbreviations_. == Organization of the repository and format The Git repository of the LTTng Documentation contains all the official versions of the documentation as separate source files. Each source file -is in its own +2.__x__+ directory, along with documentation resources -specific to this version of LTTng. You can find common source files in -the `common` directory. +is in its own `2.__x__` directory, along with documentation resources +specific to this version of LTTng. The `common` directory contains +common source files. The source files are written in -http://www.methods.co.nz/asciidoc/[AsciiDoc], a rich, lightweight markup -language with all the blocks and inline elements needed to write -backend-agnostic content. +http://www.methods.co.nz/asciidoc/[AsciiDoc] (the original, Python +version), a rich, lightweight markup language with all the blocks and +inline elements needed to write backend-agnostic content. -Although the official LTTng website uses a custom script to generate -its own HTML version of the LTTng Documentation, it is possible to -generate an autonomous HTML preview (see -link:README.adoc[`README.adoc`]). The `asciidoc.html5.conf` AsciiDoc -configuration file sets a few attributes and implements the required -macros for this preview target. +Although the official LTTng website uses a custom script to generate its +own HTML version of the LTTng Documentation, you can generate a +self-contained HTML preview (see link:README.adoc[`README.adoc`]). The +`asciidoc.html5.conf` AsciiDoc configuration file sets a few attributes +and implements the required macros for this preview target. == Validation script @@ -85,18 +79,17 @@ You need the following dependencies to run the check script: Run the check script: ---- -python3 tools/check.py 2.7/lttng-docs-2.7.txt +$ python3 tools/check.py 2.12/lttng-docs-2.12.txt ---- -Replace `2.7` by the version of the document to validate in the previous -command line. +Replace `__2.12__` with the version of the document to validate. == Style considerations -As stated in <>, the LTTng Documentation follows -the Microsoft Manual of Style (4th edition). We encourage you to read -this work before contributing a major change to the document. +As stated in "`<>`", the LTTng Documentation +follows the Microsoft Manual of Style (4th edition). We encourage you to +read this work before you contribute a major change to the document. You also need to consider the following rules, often specific to the AsciiDoc format used to write the LTTng Documentation, when you edit @@ -105,29 +98,30 @@ existing content or when you create new sections. === Macros -* **Man page references**: Always use the +man:__command__(__section__)+ - macro when you refer to a man page. +* **Manual page reference**: Always use the + `man:__PAGE__(__SECTION__)` macro when you refer to a manual page. + -.Using the `man` macro. +.Using the `manual` macro. ==== ---- -See man:lttng-ust(3) for more details about ... +See man:lttng-ust(3) to learn more about [...] ---- ==== -* [[opt-macro]] **LTTng command-line options**: Starting from v2.8, - always use the +opt:__command__(__section__):__option__+ macro when - you refer to a command-line option described in an LTTng man page. +* [[opt-macro]] **LTTng command-line option**: Starting from + LTTng{nbsp}2.8, always use the `opt:__PAGE__(__SECTION__):__OPTION__` + macro when you refer to a command-line option described in an LTTng + manual page. + .Using the `opt` macro. ==== ---- -You can use the opt:lttng-enable-event(1):--filter option to set the -filter expression of an event rule. +Use the opt:lttng-enable-event(1):--filter option to set the +filter expression of a recording event rule. ---- ==== -* **File names**: Always use the +path:{__path__}+ macro when you need +* **File name**: Always use the `path:{__PATH__}` macro when you need to write a file name. + .Using the `path` macro. @@ -137,7 +131,7 @@ Load the configuration file path:{hello.lttng} directory by default. ---- ==== -* **Directory names**: Always use the +dir:{__path__}+ macro when you +* **Directory name**: Always use the `dir:{__PATH__}` macro when you need to write a directory name. + .Using the `dir` macro. @@ -147,42 +141,42 @@ Traces are recorded to the dir:{~/lttng-traces} directory by default. ---- ==== -* **Environment variable**: Always use the +env:__VAR__+ macro when you - need to write an environment variable name. +__VAR__+ must not contain - the shell's `$` prefix. +* **Environment variable**: Always use the `env:__VAR__` macro when you + need to write an environment variable name. `__VAR__` must _not_ + contain the `$` shell prefix. + .Using the `env` macro. ==== ---- -You can set the env:LTTNG_UST_DEBUG environment variable to `1` to -activate LTTng-UST's debug output. +Set the env:LTTNG_UST_DEBUG environment variable to `1` to activate the +debug mode of LTTng-UST. ---- ==== -* **Command names**: Always use the +cmd:__cmd__+ macro when you need to - write a command name. +* **Command name**: Always use the `cmd:__COMMAND__` macro when you + need to write a command name. + .Using the `cmd` macro. ==== ---- -Run cmd:lttng-sessiond as the root user. +Run cmd:lttng-sessiond as the `root` Unix user. ---- ==== -=== Dashes +=== Dash -Em dashes can usually be written using `--` in AsciiDoc, but sometimes -the two hyphens are outputted as is, for example if the character at the -left or at the right of them is a punctuation. You can avoid this -by using the equivalent `—` HTML entity. +You can usually write an em dash with `--` in AsciiDoc, but sometimes +the AsciiDoc processor keeps them as is, for example if the character at +the left or at the right of them is a punctuation. In this case, use the +equivalent `—` HTML entity twice. .Using `--` for an em dash. ==== ---- -And yet, when the car was finally delivered--nearly three months after it -was ordered--she decided she no longer wanted it, leaving the dealer with -an oddly equipped car that would be difficult to sell. +And yet, when the car was finally delivered--nearly three months after +it was ordered--she decided she no longer wanted it, leaving the dealer +with an oddly equipped car that would be difficult to sell. ---- ==== @@ -190,13 +184,13 @@ an oddly equipped car that would be difficult to sell. ==== ---- As the frequency of recorded events increases--either because the event -throughput is actually higher or because you enabled more events than -usual—__event loss__ might be experienced. +throughput is actually higher or because you enabled more recording +event rules than usual—__event record loss__ might be experienced. ---- ==== -=== Non-breaking spaces +=== Non-breaking space Always use a non-breaking space (`{nbsp}`, or HTML entity ` `) between a quantity and its unit, or when it would be unnatural to have @@ -205,7 +199,7 @@ two related words split on two lines. .Using a non-breaking space between a quantity and its unit. ==== ---- -The size of this file is 1039{nbsp}bytes. +The size of this C{nbsp}source file is 1039{nbsp}bytes. ---- ==== @@ -217,32 +211,34 @@ This integer is displayed in base{nbsp}16. ==== -=== Placeholders in inline code +=== Placeholder in inline code When a section of an inline code element is a placeholder, or variable, -use the `+` form of the element (instead of +`+), and place `__` -around the placeholder. +use the ``+`` form of the element (instead of +`+), and place `__` +around the (preferably uppercase) placeholder. .Using a placeholder in an inline code element. ==== ---- -Name your file +something.__sys__.c+, where +__sys__+ is your system name. +Name your file +something.__SYS__.c+, where +__SYS__+ is the name of +your system. ---- ==== -=== Listing blocks +=== Listing block There are two types of listing blocks: -* [[term-box]]**Terminal boxes** are used to show commands to be entered in a - terminal exclusively, that is, the output of commands must not be - written in terminal boxes. A terminal box is an AsciiDoc literal - block with the `term` role. +* [[term-box]]A **terminal box** shows commands to be entered in a + terminal exclusively. In other words, you must _not_ write the output + of commands in a terminal box. ++ +A terminal box is an AsciiDoc literal block with the `term` role. + -Start a command line with "+${nbsp}+" to indicate that a regular Unix user -should run it. Start a command line with "+#{nbsp}+" to indicate that a -priviledged Unix user should run it. +Start a command line with "```${nbsp}```" to indicate that a regular +Unix user should run it. Start a command line with "```#{nbsp}```" to +indicate that the `root` Unix user should run it. + .Using a terminal box. ==== @@ -256,11 +252,13 @@ $ lttng enable-event --kernel --all .... ==== + -The output of a command line can be written using a simple, role-less -listing block. +Write the output of a command line with a simple, role-less listing +block. -* **Source code boxes** are used to show syntax-highlighted snippets of - source code. A source code box is an AsciiDoc source code block. +* A **source code box** shows syntax-highlighted snippets of + source code. ++ +A source code box is an AsciiDoc source code block. + .Using a source code box. ==== @@ -273,7 +271,6 @@ listing block. int main(void) { puts("Hello, World!"); - return 0; } ---- @@ -287,64 +284,69 @@ This name must be known to http://pygments.org/[Pygments]. Always indent source code examples with 4{nbsp}spaces. In any listing block, the lines must not exceed 80 characters (prefer a -maximum of 72 characters). +maximum of 72{nbsp}characters). -=== Command-line options +=== Command-line option -When specifying command-line options: +When you specify a command-line option: * Always use the long form of the option (with two hyphens). + * **If the command which accepts this option is an LTTng program**, - use the <>. Otherwise use simple backticks. -* Always follow the option name by the _option_ word. + use the <>. Otherwise, use simple backticks. + +* Always follow the option name with the _option_ word. .Using a command-line option. ==== ---- -You can use the `lttng` tool's opt:lttng(1):--group option to specify a -custom tracing group. +You can use the opt:lttng(1):--group option of the cmd:lttng tool to +specify your custom tracing group. ---- ==== -In <>, always put `=` between the option name +In a <>, always put `=` between the option name and its argument, if any. .Terminal box. ==== In this example, `provider:'sys_*'` is not the argument of the -`--userspace` option: it's the first positional argument, and -the `--userspace` option has no arguments. +`--userspace` option: it's the first non-option argument, and the +`--userspace` option has no arguments. [listing] .... [role="term"] ---- $ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \ - --exclude=sys_send,sys_block --loglevel=TRACE_INFO + --exclude=sys_send,sys_block --loglevel=INFO ---- .... ==== -=== Procedures +=== Procedure Use an ordered list to write a procedure. -If a step is optional, prepend `**Optional**:` followed by a space to -the step's first sentence. Start the first sentence with a capital -letter. Do not use an optional step followed by a condition; use a -conditional step for this. +If a step is optional, prepend `+**Optional**:+` followed with a space +to the first sentence of the step. + +Start the first sentence with a capital letter. + +Don't use an optional step followed with a condition; use a conditional +step for this. If a step is conditional, put the condition (_If something_) in bold, -followed by a comma, followed by the step itself. +followed with a comma, followed with the step itself. -=== External links +=== External link -When using a hyperlink to an LTTng repository's file or directory, -link to the GitHub code browser. Make sure to link to the appropriate -Git branch (usually +stable-2.__x__+). You can use the `revision` +When using a hyperlink to a file/directory of an LTTng repository, link +to the GitHub code browser. Make sure to link to the appropriate Git +branch (usually `stable-2.__x__`). You can use the `revision` AsciiDoc attribute in the URL. .Link to source file. @@ -357,351 +359,17 @@ for more details about [...] ==== -=== "Since" sections +=== "`Since`" sections If a whole section describes a feature which was introduced in LTTng 2.1 -or later, add the +since-2.__x__+ role to the section's heading, where -+__x__+ is the minor version of the LTTng release which introduced -the feature. +or later, assign the `since-2.__x__` role to the section, where `__x__` +is the minor version of the LTTng release which introduced the feature. .Section heading describing a feature introduced in LTTng 2.5. ==== ---- [role="since-2.5"] [[tracef]] -==== Use `tracef()` +==== Use `lttng_ust_tracef()` ---- ==== - - -[[terminology]] -== Terminology - -What follows is an official, partial list of technical terms used by the -LTTng Documentation. Other forms of those terms are _not_ permitted. For -example, do not write `use-case` or `filesystem`. - -Autotools:: - The GNU Autotools. -+ -Do not use _autotools_. - -Babeltrace:: - The Babeltrace project, which includes the `babeltrace` command, some - libraries, and Python bindings. -+ -Use +`babeltrace`+ to refer to the actual `babeltrace` command. - -Babeltrace Python bindings:: - The Python bindings of Babeltrace. -+ -The plural _bindings_ is important. - -Bash:: - The Bash shell. -+ -Do not use _bash_. - -buffering scheme:: - A layout of tracing buffers applied to a given channel. - -channel:: - An LTTng channel. - -CLI:: - Prefer expanding this acronym to _command-line interface_ in the text. - -clock:: - A reference of time for a tracer. -+ -Use _system time_ to refer to the date and time as seen by a user. - -command-line:: - Adjective version of _command line_: _command-line option_, - _command-line interface_. - -command-line interface:: - An interface in which the user enters command lines to instruct the - system what to do. -+ -Prefer using _command_ or _command-line tool_ to refer to a -specific command. - -command line:: - An actual line of command entered by the user in a terminal, at a - command prompt. -+ -Write _command-line_ when used as an adjective. - -consumer daemon:: - The LTTng consumer daemon. -+ -Do not use _consumerd_. -+ -Use +`lttng-consumerd`+ to refer to the consumer daemon -executable. - -domain:: - Do not use when referring to a _tracing domain_. - -event:: - Occurrence recognised by software, emitted by a tracer when specific - conditions are met, at a given time. An event _occurs_ at a specific - time, after which a tracer can record its payload. - -event loss mode:: - The mechanism by which event records of a given channel are lost - (not recorded) when there is no sub-buffer space left to store them. - -event name:: - The name of an event, which is also the name of the event record. - This is different from a _tracepoint name_, which is only the name - of the instrumentation point, not necessarily equal to the event - name. - -event record:: - Record, in a trace, of the payload of an event which occured. - -event rule:: - Set of conditions which must be satisfied for one or more events - to occur. The `lttng enable-event` command creates and enables - _event rules_, not _events_. - -file system:: - Contains directories, files, and links in an organized structure. -+ -Do not use _filesystem_ or _file-system_. - -+`java.util.logging`+:: - Even though the `--jul` command-line option is an acronym for this - term, there is no such thing as _Java Util Logging_. The only - correct form is the name of the Java package, - +`java.util.logging`+. - -instrumentation:: - The use of LTTng probes to make a software traceable. - -libc:: - Do not use. -+ -Use _the C standard library_ to refer to the standard library for -the C programming language, or _glibc_ to refer to the GNU C Library -specifically. - -log4j:: - LTTng-UST supports Java logging using Apache _log4j_, not Apache - Log4j 2. - -log level:: - Level of severity of a log statement. -+ -Do not hyphenate. - -kernel:: - In general, do not use _kernel_ to refer to the _Linux kernel_: use - the whole _Linux kernel_ term, because other operating system kernels - exist. Since the _L_ in _LTTng_ means _Linux_, it's okay to use _LTTng - kernel modules_. - -Linux Trace Toolkit: next generation:: - The expansion of the _LTTng_ acronym. -+ -The colon and the lowercase _n_ and _g_ are important. - -LTTng-analyses:: - The LTTng-analyses project. - -LTTng-modules:: - The LTTng-modules project. - -LTTng-tools:: - The LTTng-tools project. - -LTTng-UST:: - The LTTng-UST project. - -LTTng-UST Java agent:: -LTTng-UST Python agent:: - An LTTng user space agent. -+ -Do not use _Java LTTng-UST agent_ or _Python LTTng-UST agent_. - -LTTng Documentation:: - The name of this project. -+ -Do not use _LTTng documentation_. -+ -When referring to the project, the _the_ determiner can be lowercase: -_Welcome to the LTTng Documentation!_. - -LTTng live:: - The name of a communication protocol between Babeltrace and the - relay daemon which makes it possible to see events "live", - as they are received by the relay daemon. -+ -Do not hyphenate. - -the +`lttng`+ tool:: -the +`lttng`+ command line tool:: - The `lttng` command line tool. -+ -When _tool_ has been mentioned in the previous sentences, you can use -+`lttng`+ alone. - -Makefile:: - An input for the make tool. -+ -Do not use _makefile_ or _make file_. - -man page:: - Unix-style reference manual page. -+ -Do not hyphenate. - -per-process buffering:: - A buffering scheme in which each process has its own buffer for a - given user space channel. -+ -Do not use _per-PID buffering_. - -per-user buffering:: - A buffering scheme in which all the processes of a user share the same - buffer for a given user space channel. -+ -Do not use _per-UID buffering_. - -probe:: - An instrumentation point. -+ -Prefer _tracepoint_ when referring to a user space or Linux kernel -LTTng tracepoint. - -real-time clock:: - A clock which keeps track of the current time, including eventual - time corrections. -+ -Do not use _realtime clock_ or _real time clock_. - -relay daemon:: - The LTTng relay daemon. -+ -Do not use _relayd_. -+ -Use +`lttng-relayd`+ to refer to the relay daemon executable. - -root user:: - A superuser of a Linux system. -+ -Do not use +`root`+. - -session:: - Do not use when referring to a _tracing session_. - -session daemon:: - The LTTng session daemon. -+ -Do not use _sessiond_. -+ -Use +`lttng-sessiond`+ to refer to the session daemon -executable. - -snapshot:: - Copy of the current data of all the buffers of a given tracing - session, saved as a trace. - -sub-buffer:: - One part of an LTTng ring buffer. -+ -Do not use _subbuffer_ since it's harder to read with the two -contiguous b's. - -timestamp:: - Time information attached to an event when it is emitted. This is not - necessarily a _Unix timestamp_. -+ -Do not use _time stamp_. - -trace:: - As a verb: a user or a tracer can _trace_ an application. - -Trace Compass:: - The Trace Compass project and application. -+ -Do not hyphenate. Do not use _Trace compass_, _TraceCompass_, or -_Tracecompass_. - -tracepoint:: - An instrumentation point using the tracepoint mechanism of - the Linux kernel or of LTTng-UST. -+ -Do not use _trace point_ or _trace-point_. - -tracepoint definition:: - The definition of a single tracepoint. - -tracepoint name:: - The name of a _tracepoint_. -+ -Not to be confused with an _event name_. - -tracepoint provider:: - A set of functions providing tracepoints to an instrumented user - application. -+ -Not to be confused with a _tracepoint provider package_: many tracepoint -providers can exist within a tracepoint provider package. - -tracepoint provider package:: - One or more tracepoint providers compiled as an object file or as - a shared library. - -tracing domain:: - An LTTng tracing domain. -+ -Always use the complete _tracing domain_ term, not _domain_ alone, -unless _tracing domain_ has been used in the few preceding sentences. - -tracing group:: - The Unix group in which a user can be to be allowed to trace the - Linux kernel. -+ -Do not use _`tracing` group_, as the name of the tracing -group is configurable. - -tracing session:: - An LTTng tracing session. -+ -Always use the complete _tracing session_ term, not _session_ alone. - -Unix:: - Unix operating system or philosophy. -+ -Do not use _UNIX_. - -Unix epoch:: - Absolute reference of a real-time clock. -+ -Use the term as a proper noun: do not precede it with _the_. -+ -Do not use _Epoch_ alone. - -Unix timestamp:: - Timestamp represented as the number of seconds since Unix epoch. - -use case:: - According to Wikipedia: List of actions or event steps, typically - defining the interactions between a role and a system, to - achieve a goal. -+ -Do not hyphenate. - -user application:: - An application running in user space, as opposed to a Linux kernel - module, for example. -+ -Do not use _user space application_, as this is redundant. - -user space:: - User processes. -+ -Do not hyphenate. -- 2.34.1