2.9: do not use xref, use <<...>> with attribute list

[lttng-docs.git] / CONTRIBUTING.adoc

diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc
index 6828fb9e4506a99dc5177ecc8fdca07973084645..50776704de35fc127409fa05f7e05bc92aa8ad5e 100644 (file)
--- a/CONTRIBUTING.adoc
+++ b/CONTRIBUTING.adoc
@@ -1,7 +1,7 @@
 The LTTng Documentation: Contributor's guide
 ============================================
 Philippe Proulx
 The LTTng Documentation: Contributor's guide
 ============================================
 Philippe Proulx

-v1.0, 21 October 2016
+v1.0, 26 October 2016

 
 This guide presents the structure and conventions of the LTTng
 Documentation's source. Make sure you read it thoroughly before
 
 This guide presents the structure and conventions of the LTTng
 Documentation's source. Make sure you read it thoroughly before


@@ -106,9 +106,7 @@ existing content or when you create new sections.
 === Macros
 
 * **Man page references**: Always use the +man:__command__(__section__)+
 === Macros
 
 * **Man page references**: Always use the +man:__command__(__section__)+

-  macro you refer to a man page. The official online version of the
-  LTTng Documentation has hyperlinks to the correct online versions
-  of the LTTng man pages thanks to this macro.
+  macro when you refer to a man page.

 +
 .Using the `man` macro.
 ====
 +
 .Using the `man` macro.
 ====


@@ -117,8 +115,20 @@ See man:lttng-ust(3) for more details about ...
 ----
 ====
 
 ----
 ====
 

-* **File names**: Always use the +path:{__path__}+
-  macro when you need to write a file name.
+* [[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.
++
+.Using the `opt` macro.
+====
+----
+You can use the opt:lttng-enable-event(1):--filter option to set the
+filter expression of an event rule.
+----
+====
+
+* **File names**: Always use the +path:{__path__}+ macro when you need
+  to write a file name.

 +
 .Using the `path` macro.
 ====
 +
 .Using the `path` macro.
 ====


@@ -127,8 +137,8 @@ Load the configuration file path:{hello.lttng} directory by default.
 ----
 ====
 
 ----
 ====
 

-* **Directory names**: Always use the +dir:{__path__}+
-  macro when you need to write a directory name.
+* **Directory names**: Always use the +dir:{__path__}+ macro when you
+  need to write a directory name.

 +
 .Using the `dir` macro.
 ====
 +
 .Using the `dir` macro.
 ====


@@ -137,9 +147,9 @@ 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's `$` prefix.

 +
 .Using the `env` macro.
 ====
 +
 .Using the `env` macro.
 ====


@@ -149,8 +159,8 @@ activate LTTng-UST's debug output.
 ----
 ====
 
 ----
 ====
 

-* **Command names**: Always use the +cmd:__cmd__+
-  macro when you need to write a command name.
+* **Command names**: Always use the +cmd:__cmd__+ macro when you need to
+  write a command name.

 +
 .Using the `cmd` macro.
 ====
 +
 .Using the `cmd` macro.
 ====


@@ -230,14 +240,18 @@ There are two types of listing blocks:
   written in terminal boxes. A terminal box is an AsciiDoc literal
   block with the `term` role.
 +
   written in terminal boxes. 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.
++

 .Using a terminal box.
 ====
 [listing]
 ....
 [role="term"]
 ----
 .Using a terminal box.
 ====
 [listing]
 ....
 [role="term"]
 ----

-lttng create my-session
-lttng enable-event --kernel --all
+$ lttng create my-session
+$ lttng enable-event --kernel --all

 ----
 ....
 ====
 ----
 ....
 ====


@@ -281,14 +295,15 @@ maximum of 72 characters).
 When specifying command-line options:
 
 * Always use the long form of the option (with two hyphens).
 When specifying command-line options:
 
 * Always use the long form of the option (with two hyphens).

-* Use a code element for the option name (backticks).
+* **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.
 
 .Using a command-line option.
 ====
 ----
 * Always follow the option name by the _option_ word.
 
 .Using a command-line option.
 ====
 ----

-You can use the `lttng` tool's `--group` option to specify a custom
-tracing group.
+You can use the `lttng` tool's opt:lttng(1):--group option to specify a
+custom tracing group.

 ----
 ====
 
 ----
 ====
 


@@ -305,7 +320,7 @@ the `--userspace` option has no arguments.
 ....
 [role="term"]
 ----
 ....
 [role="term"]
 ----

-lttng enable-event --userspace provider:'sys_*' --filter='field < 23'
+$ lttng enable-event --userspace provider:'sys_*' --filter='field < 23' \

                    --exclude=sys_send,sys_block --loglevel=TRACE_INFO
 ----
 ....
                    --exclude=sys_send,sys_block --loglevel=TRACE_INFO
 ----
 ....