From: Philippe Proulx <eeppeliteloop@gmail.com>
Date: Thu, 24 Mar 2016 07:42:10 +0000 (-0400)
Subject: doc/man: add nloption and genoption AsciiDoc macros
X-Git-Tag: v2.8.0~171
X-Git-Url: https://git.lttng.org./?a=commitdiff_plain;h=1cdba6777484ff3638f24990e14095c668dfea53;p=lttng-tools.git

doc/man: add nloption and genoption AsciiDoc macros

See the updated README.md for details.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---

diff --git a/doc/man/README.md b/doc/man/README.md
index eb73ded2c..fc8c81c77 100644
--- a/doc/man/README.md
+++ b/doc/man/README.md
@@ -34,11 +34,28 @@ Usage example: `linklttng:lttng-enable-channel(1)`.
 
 ### option
 
-The option macro is used to write a command-line option.
+The option macro is used to write a command-line option which is
+defined in the same man page.
 
 Usage example: `option:--no-output`, `option:--loglevel=TRACE_WARNING`
 
 
+### nloption
+
+Command-line option generating no link. This is used when talking
+about a generic option which is defined in many man pages.
+
+Usage example: `nloption:--jul`
+
+
+### genoption
+
+General (`lttng(1)`) command-line option, for generating the appropriate
+cross-man-page link.
+
+Usage example: `genoption:--group`, `genoption:--sessiond-path`
+
+
 ### not
 
 The `:not:` macro is used to emphasize on _not_.
diff --git a/doc/man/asciidoc.conf b/doc/man/asciidoc.conf
index 3f8cac41e..3410dd2a3 100644
--- a/doc/man/asciidoc.conf
+++ b/doc/man/asciidoc.conf
@@ -8,6 +8,16 @@
 # Usage: linklttng:command(manpage-section)
 (?su)[\\]?(?P<name>linklttng):(?P<target>\S*?)\((?P<attrlist>.*?)\)=
 
+# no link option macro
+#
+# Usage: nloption:--option-name
+(?su)[\\]?(?P<name>nloption):(?P<opt>--?[a-zA-Z0-9-]*)=
+
+# lttng(1) general option macro
+#
+# Usage: genoption:--option-name
+(?su)[\\]?(?P<name>genoption):(?P<opt>--?[a-zA-Z0-9-]*)=
+
 # option macro
 #
 # Usage: option:--option-name
@@ -33,6 +43,18 @@ ifdef::backend-docbook[]
 <literal>{opt}</literal>
 endif::backend-docbook[]
 
+# no link option macro expansions
+ifdef::backend-docbook[]
+[nloption-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+
+# lttng(1) general option macro expansions
+ifdef::backend-docbook[]
+[genoption-inlinemacro]
+<literal>{opt}</literal>
+endif::backend-docbook[]
+
 # not macro expansions
 ifdef::backend-docbook[]
 [not-inlinemacro]
diff --git a/doc/man/common-cmd-footer.txt b/doc/man/common-cmd-footer.txt
index cbd3c3913..da241ec96 100644
--- a/doc/man/common-cmd-footer.txt
+++ b/doc/man/common-cmd-footer.txt
@@ -16,7 +16,7 @@ ENVIRONMENT VARIABLES
 `LTTNG_SESSIOND_PATH`::
     Full session daemon binary path.
 +
-The option:--sessiond-path option has precedence over this
+The genoption:--sessiond-path option has precedence over this
 environment variable.
 
 Note that the linklttng:lttng-create(1) command can spawn an LTTng
diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt
index ce37426c7..2af6fe55d 100644
--- a/doc/man/lttng.1.txt
+++ b/doc/man/lttng.1.txt
@@ -33,19 +33,19 @@ A _tracing domain_ is a tracer category. There are five available
 domains. For some commands, the domain needs to be specified with a
 command-line option. The domain options are:
 
-option:-j, option:--jul::
+nloption:-j, nloption:--jul::
     Apply command to the `java.util.logging` (JUL) domain.
 
-option:-k, option:--kernel::
+nloption:-k, nloption:--kernel::
     Apply command to the Linux kernel domain.
 
-option:-l, option:--log4j::
+nloption:-l, nloption:--log4j::
     Apply command to the Apache log4j 1.2 (Java) domain.
 
-option:-p, option:--python::
+nloption:-p, nloption:--python::
     Apply command to the Python domain.
 
-option:-u, option:--userspace::
+nloption:-u, nloption:--userspace::
     Apply command to the user space domain.
 
 The LTTng session daemon is a tracing registry which allows the user to
@@ -139,7 +139,7 @@ option:-V, option:--version::
 
 COMMANDS
 --------
-The following commands also have their own option:--help option.
+The following commands also have their own nloption:--help option.
 
 
 Tracing sessions