-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 <<terminology,Terminology>> 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
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 <<principles,Principles>>, 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 "`<<principles,Principles>>`", 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
=== 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.
----
====
-* **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.
----
====
-* **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.
----
====
====
----
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
.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.
----
====
====
-=== 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.
====
....
====
+
-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.
====
int main(void)
{
puts("Hello, World!");
-
return 0;
}
----
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 <<opt-macro,`opt` macro>>. Otherwise use simple backticks.
-* Always follow the option name by the _option_ word.
+ use the <<opt-macro,`opt` macro>>. 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 <<term-box,terminal boxes>>, always put `=` between the option name
+In a <<term-box,terminal box>>, 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.
====
-=== "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.
projects / lttng-docs.git / commitdiff
