doc/man: make default values of boolean init. params. clearer

This patch answers to <https://bugs.lttng.org/issues/1387>, removing the
"=`yes`" and "=`no`" in the component class manual pages to replace them
with "='VAL'" and indicate the behaviour depending on "'VAL'", as well
as the default value.

Fixes: https://bugs.lttng.org/issues/1387
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Ie7439fa397e2a9a5818152a68073f7bf87385675
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10709
(cherry picked from commit 6f6e5e6146d1d55f9d49b587a64e2b32ebc29064)
Reviewed-on: https://review.lttng.org/c/babeltrace/+/10726

diff --git a/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt
index f98c7d7c29e599581cbe8626056485fd94aeebda..bccd85491c262e72b2b3bf6e63d7f35b52b1ca0c 100644 (file)
--- a/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt
+++ b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-filter.lttng-utils.debug-info(7)
 :manpagetype: component class
 = babeltrace2-filter.lttng-utils.debug-info(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 :compcls: compcls:filter.lttng-utils.debug-info
 :defdebuginfoname: `debug_info`
 
 :compcls: compcls:filter.lttng-utils.debug-info
 :defdebuginfoname: `debug_info`
 


@@ -229,10 +229,12 @@ param:debug-info-field-name='NAME' vtype:[optional string]::
     of the created events 'NAME' instead of the default
     {defdebuginfoname}.
 
     of the created events 'NAME' instead of the default
     {defdebuginfoname}.
 

-param:full-path=`yes` vtype:[optional boolean]::
-    Use the full path when writing the executable name (`bin`) and
-    source file name (`src`) fields in the {defdebuginfoname} context
-    field of the created events.
+param:full-path='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then use the full path when writing the executable
+    name (`bin`) and source file name (`src`) fields in the
+    {defdebuginfoname} context field of the created events.
++
+Default: false.

 
 param:target-prefix='DIR' vtype:[optional string]::
     Use 'DIR' as the root directory of the target file system instead of
 
 param:target-prefix='DIR' vtype:[optional string]::
     Use 'DIR' as the root directory of the target file system instead of

diff --git a/doc/man/babeltrace2-filter.utils.trimmer.7.txt b/doc/man/babeltrace2-filter.utils.trimmer.7.txt
index b1f754e5810c64eb3efcefbbcae4e919beaf2f83..707aac6c4a1dacd8df0060f1f9f5e8aacda4ef85 100644 (file)
--- a/doc/man/babeltrace2-filter.utils.trimmer.7.txt
+++ b/doc/man/babeltrace2-filter.utils.trimmer.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-filter.utils.trimmer(7)
 :manpagetype: component class
 = babeltrace2-filter.utils.trimmer(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -74,9 +74,11 @@ treats it as such.
 If you don't specify this parameter, the component discards no events
 from the beginning of the trimming time range.
 
 If you don't specify this parameter, the component discards no events
 from the beginning of the trimming time range.
 

-param:gmt=`yes` vtype:[optional boolean]::
-    Set the time zone of the param:begin and param:end parameters
-    to GMT instead of the local time zone.
+param:gmt='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then set the time zone of the param:begin and
+    param:end parameters to GMT instead of the local time zone.
++
+Default: false.

 
 
 == PORTS
 
 
 == PORTS

diff --git a/doc/man/babeltrace2-sink.ctf.fs.7.txt b/doc/man/babeltrace2-sink.ctf.fs.7.txt
index df91341489b2aa484258d19b466a56e15eb02f2f..736602772465acc23c9d045e033a0d26f1448090 100644 (file)
--- a/doc/man/babeltrace2-sink.ctf.fs.7.txt
+++ b/doc/man/babeltrace2-sink.ctf.fs.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-sink.ctf.fs(7)
 :manpagetype: component class
 = babeltrace2-sink.ctf.fs(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -194,18 +194,24 @@ until the path does not exist.
 
 == INITIALIZATION PARAMETERS
 
 
 == INITIALIZATION PARAMETERS
 

-param:assume-single-trace=`yes` vtype:[optional boolean]::
-    Assume that the component only receives messages related to a single
-    input trace.
+param:assume-single-trace='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then assume that the component only receives
+    messages related to a single input trace.

 +
 This parameter affects how the component builds the output trace path
 (see <<output-path,``Output path''>>).
 +
 This parameter affects how the component builds the output trace path
 (see <<output-path,``Output path''>>).

++
+Default: false.

 
 

-param:ignore-discarded-events=`yes` vtype:[optional boolean]::
-    Ignore discarded events messages.
+param:ignore-discarded-events='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then ignore discarded events messages.
++
+Default: false.

 
 

-param:ignore-discarded-packets=`yes` vtype:[optional boolean]::
-    Ignore discarded packets messages.
+param:ignore-discarded-packets='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then ignore discarded packets messages.
++
+Default: false.

 
 param:path='PATH' vtype:[string]::
     Base output path.
 
 param:path='PATH' vtype:[string]::
     Base output path.


@@ -213,8 +219,10 @@ param:path='PATH' vtype:[string]::
 See <<output-path,``Output path''>> to learn how the component uses this
 parameter to build the output path for a given input trace.
 
 See <<output-path,``Output path''>> to learn how the component uses this
 parameter to build the output path for a given input trace.
 

-param:quiet=`yes` vtype:[optional boolean]::
-    Do not write anything to the standard output.
+param:quiet='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then do not write anything to the standard output.
++
+Default: false.

 
 
 == PORTS
 
 
 == PORTS

diff --git a/doc/man/babeltrace2-sink.text.details.7.txt b/doc/man/babeltrace2-sink.text.details.7.txt
index dc8792194ec4669c8bec0c9c4e976925e927dae8..8a23dd4e49fccd475d4c10312902b2f58d52dec7 100644 (file)
--- a/doc/man/babeltrace2-sink.text.details.7.txt
+++ b/doc/man/babeltrace2-sink.text.details.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-sink.text.details(7)
 :manpagetype: component class
 = babeltrace2-sink.text.details(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -113,8 +113,8 @@ param:color=(`never` | `auto` | `always`) vtype:[optional string]::
 The `BABELTRACE_TERM_COLOR` environment variable overrides this
 parameter.
 
 The `BABELTRACE_TERM_COLOR` environment variable overrides this
 parameter.
 

-param:compact=`yes` vtype:[optional boolean]::
-    Enable compact mode.
+param:compact='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then enable compact mode.

 +
 In compact mode, the component prints one line per message, omitting
 many details about messages. This is useful if you only need the time,
 +
 In compact mode, the component prints one line per message, omitting
 many details about messages. This is useful if you only need the time,


@@ -122,24 +122,38 @@ type, and very basic information of messages.
 +
 In compact mode, the component still prints the full metadata blocks.
 You can remove such blocks with the param:with-metadata parameter.
 +
 In compact mode, the component still prints the full metadata blocks.
 You can remove such blocks with the param:with-metadata parameter.

++
+Default: false.

 
 

-param:with-metadata=`no` vtype:[optional boolean]::
-    Do not print metadata blocks.
+param:with-metadata='VAL' vtype:[optional boolean]::
+    If 'VAL' is false, then do not print metadata blocks.
++
+Default: true.

 
 

-param:with-stream-class-name=`no` vtype:[optional boolean]::
-    Do not print stream class names.
+param:with-stream-class-name='VAL' vtype:[optional boolean]::
+    If 'VAL' is false, then do not print stream class names.
++
+Default: true.

 
 

-param:with-stream-name=`no` vtype:[optional boolean]::
-    Do not print stream names.
+param:with-stream-name='VAL' vtype:[optional boolean]::
+    If 'VAL' is false, then do not print stream names.
++
+Default: true.

 
 

-param:with-time=`no` vtype:[optional boolean]::
-    Do not print timing information.
+param:with-time='VAL' vtype:[optional boolean]::
+    If 'VAL' is false, then do not print timing information.
++
+Default: true.

 
 

-param:with-trace-name=`no` vtype:[optional boolean]::
-    Do not print trace names.
+param:with-trace-name='VAL' vtype:[optional boolean]::
+    If 'VAL' is false, then do not print trace names.
++
+Default: true.

 
 

-param:with-uuid=`no` vtype:[optional boolean]::
-    Do not print UUIDs.
+param:with-uuid='VAL' vtype:[optional boolean]::
+    If 'VAL' is false, then do not print UUIDs.
++
+Default: true.

 
 
 == PORTS
 
 
 == PORTS

diff --git a/doc/man/babeltrace2-sink.text.pretty.7.txt b/doc/man/babeltrace2-sink.text.pretty.7.txt
index 6d0cd292529542adc789e8f409ad5b88c8756c7f..496879117354bb80bda174c00996560be9321276 100644 (file)
--- a/doc/man/babeltrace2-sink.text.pretty.7.txt
+++ b/doc/man/babeltrace2-sink.text.pretty.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-sink.text.pretty(7)
 :manpagetype: component class
 = babeltrace2-sink.text.pretty(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -43,20 +43,28 @@ man:babeltrace(1) (Babeltrace~1 command-line tool).
 
 == INITIALIZATION PARAMETERS
 
 
 == INITIALIZATION PARAMETERS
 

-param:clock-cycles=`yes` vtype:[optional boolean]::
-    Print event times in clock cycles instead of hours, minutes,
-    seconds, and nanoseconds.
+param:clock-cycles='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then print event times in clock cycles instead of
+    hours, minutes, seconds, and nanoseconds.
++
+Default: false.

 
 

-param:clock-date=`yes` vtype:[optional boolean]::
-    Print event times _and_ dates.
+param:clock-date='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then print event times _and_ dates.
++
+Default: false.

 
 

-param:clock-gmt=`yes` vtype:[optional boolean]::
-    Print event times in the GMT time zone instead of the local time
-    zone.
+param:clock-gmt='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then print event times in the GMT time zone
+    instead of the local time zone.
++
+Default: false.

 
 

-param:clock-seconds=`yes` vtype:[optional boolean]::
-    Print event times in seconds instead of hours, minutes,
-    seconds, and nanoseconds.
+param:clock-seconds='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then print event times in seconds instead of
+    hours, minutes, seconds, and nanoseconds.
++
+Default: false.

 
 param:color=(`never` | `auto` | `always`) vtype:[optional string]::
     Force the terminal color support, one of:
 
 param:color=(`never` | `auto` | `always`) vtype:[optional string]::
     Force the terminal color support, one of:


@@ -80,52 +88,200 @@ param:field-default=(`show` | `hide`) vtype:[optional string]::
     By default, show or hide all the fields. This sets the default value
     of all the parameters which start with `field-`.
 
     By default, show or hide all the fields. This sets the default value
     of all the parameters which start with `field-`.
 

-param:field-emf=(`yes` | `no`) vtype:[optional boolean]::
+param:field-emf='VAL' vtype:[optional boolean]::

     Show or hide the event's Eclipse Modeling Framework URI field.
     Show or hide the event's Eclipse Modeling Framework URI field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True
+
+`hide`::
+    False
+
+Not set::
+    False
+--

 
 

-param:field-loglevel=(`yes` | `no`) vtype:[optional boolean]::
+param:field-loglevel='VAL' vtype:[optional boolean]::

     Show or hide the event's logging level field.
     Show or hide the event's logging level field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True

 
 

-param:field-trace=(`yes` | `no`) vtype:[optional boolean]::
+`hide`::
+    False
+
+Not set::
+    False
+--
+
+param:field-trace='VAL' vtype:[optional boolean]::

     Show or hide the trace name field.
     Show or hide the trace name field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True

 
 

-param:field-trace:domain=(`yes` | `no`) vtype:[optional boolean]::
+`hide`::
+    False
+
+Not set::
+    False
+--
+
+param:field-trace:domain='VAL' vtype:[optional boolean]::

     Show or hide the tracing domain field.
     Show or hide the tracing domain field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True
+
+`hide`::
+    False
+
+Not set::
+    False
+--

 
 

-param:field-trace:hostname=(`yes` | `no`) vtype:[optional boolean]::
+param:field-trace:hostname='VAL' vtype:[optional boolean]::

     Show or hide the hostname field.
     Show or hide the hostname field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True

 
 

-param:field-trace:procname=(`yes` | `no`) vtype:[optional boolean]::
+`hide`::
+    False
+
+Not set::
+    True
+--
+
+param:field-trace:procname='VAL' vtype:[optional boolean]::

     Show or hide the process name field.
     Show or hide the process name field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True

 
 

-param:field-trace:vpid=(`yes` | `no`) vtype:[optional boolean]::
+`hide`::
+    False
+
+Not set::
+    True
+--
+
+param:field-trace:vpid='VAL' vtype:[optional boolean]::

     Show or hide the virtual process ID field.
     Show or hide the virtual process ID field.

++
+Default, depending on the param:field-default parameter:
++
+--
+`show`::
+    True

 
 

-param:name-context=(`yes` | `no`) vtype:[optional boolean]::
-    Show or hide the field names in the context scopes.
+`hide`::
+    False
+
+Not set::
+    True
+--

 
 param:name-default=(`show` | `hide`) vtype:[optional string]::
     By default, show or hide all the names. This sets the
     default value of all the parameters which start with `name-`.
 
 
 param:name-default=(`show` | `hide`) vtype:[optional string]::
     By default, show or hide all the names. This sets the
     default value of all the parameters which start with `name-`.
 

-param:name-header=(`yes` | `no`) vtype:[optional boolean]::
+param:name-header='VAL' vtype:[optional boolean]::

     Show or hide the field names in the header scopes.
     Show or hide the field names in the header scopes.

++
+Default, depending on the param:name-default parameter:
++
+--
+`show`::
+    True
+
+`hide`::
+    False
+
+Not set::
+    False
+--

 
 

-param:name-payload=(`yes` | `no`) vtype:[optional boolean]::
+param:name-context='VAL' vtype:[optional boolean]::
+    Show or hide the field names in the context scopes.
++
+Default, depending on the param:name-default parameter:
++
+--
+`show`::
+    True
+
+`hide`::
+    False
+
+Not set::
+    True
+--
+
+param:name-payload='VAL' vtype:[optional boolean]::

     Show or hide the field names in the event payload scopes.
     Show or hide the field names in the event payload scopes.

++
+Default, depending on the param:name-default parameter:
++
+--
+`show`::
+    True
+
+`hide`::
+    False
+
+Not set::
+    True
+--

 
 

-param:name-scope=(`yes` | `no`) vtype:[optional boolean]::
+param:name-scope='VAL' vtype:[optional boolean]::

     Show or hide the scope names.
     Show or hide the scope names.

++
+Default, depending on the param:name-default parameter:
++
+--
+`show`::
+    True

 
 

-param:no-delta=`yes` vtype:[optional boolean]::
-    Do not print the time delta between consecutive lines.
+`hide`::
+    False
+
+Not set::
+    False
+--
+
+param:no-delta='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then do not print the time delta between
+    consecutive lines.
++
+Default: false.

 
 param:path='PATH' vtype:[optional string]::
     Print the text output to the file 'PATH' instead of the standard
     output.
 
 
 param:path='PATH' vtype:[optional string]::
     Print the text output to the file 'PATH' instead of the standard
     output.
 

-param:verbose=`yes` vtype:[optional boolean]::
-    Turn the verbose mode on.
+param:verbose='VAL' vtype:[optional boolean]::
+    If 'VAL' if true, then turn the verbose mode on.
++
+Default: false.

 
 
 == PORTS
 
 
 == PORTS

diff --git a/doc/man/babeltrace2-sink.utils.counter.7.txt b/doc/man/babeltrace2-sink.utils.counter.7.txt
index 60f051d50abf176e779854cd01d823a17e139888..082750a0c634ec8804eb92711358cd34494a76e5 100644 (file)
--- a/doc/man/babeltrace2-sink.utils.counter.7.txt
+++ b/doc/man/babeltrace2-sink.utils.counter.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-sink.utils.counter(7)
 :manpagetype: component class
 = babeltrace2-sink.utils.counter(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -54,8 +54,11 @@ the zero counts with the param:hide-zero parameter.
 
 == INITIALIZATION PARAMETERS
 
 
 == INITIALIZATION PARAMETERS
 

-param:hide-zero=`yes` vtype:[optional boolean]::
-    Do not print the statistics lines where the count is zero.
+param:hide-zero='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then do not print the statistics lines where the
+    count is zero.
++
+Default: false.

 
 param:step='STEP' vtype:[optional unsigned integer]::
     Print a new block of statistics every 'STEP' consumed messages
 
 param:step='STEP' vtype:[optional unsigned integer]::
     Print a new block of statistics every 'STEP' consumed messages

diff --git a/doc/man/babeltrace2-source.ctf.fs.7.txt b/doc/man/babeltrace2-source.ctf.fs.7.txt
index fe3ff3222b128a20c32d3032adc1ec14f8244019..15ab96e40367cd46cf724d81b3b9af0d2783c846 100644 (file)
--- a/doc/man/babeltrace2-source.ctf.fs.7.txt
+++ b/doc/man/babeltrace2-source.ctf.fs.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-source.ctf.fs(7)
 :manpagetype: component class
 = babeltrace2-source.ctf.fs(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -144,9 +144,12 @@ param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
 You can combine this parameter with the param:clock-class-offset-ns
 parameter.
 
 You can combine this parameter with the param:clock-class-offset-ns
 parameter.
 

-param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
-    Force the origin of all clock classes that the component creates to
-    have a Unix epoch origin, whatever the detected tracer.
+param:force-clock-class-origin-unix-epoch='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then force the origin of all clock classes that
+    the component creates to have a Unix epoch origin, whatever the
+    detected tracer.
++
+Default: false.

 
 param:inputs='DIRS' vtype:[array of strings]::
     Open and read the physical CTF traces located in 'DIRS'.
 
 param:inputs='DIRS' vtype:[array of strings]::
     Open and read the physical CTF traces located in 'DIRS'.

diff --git a/doc/man/babeltrace2-source.text.dmesg.7.txt b/doc/man/babeltrace2-source.text.dmesg.7.txt
index 9079fe4b4331890a85c016019187e4a3d84e5e5a..1e75c9d29870da0d5e7ecb04b1e83ca238a78736 100644 (file)
--- a/doc/man/babeltrace2-source.text.dmesg.7.txt
+++ b/doc/man/babeltrace2-source.text.dmesg.7.txt
@@ -1,6 +1,6 @@
 = babeltrace2-source.text.dmesg(7)
 :manpagetype: component class
 = babeltrace2-source.text.dmesg(7)
 :manpagetype: component class

-:revdate: 14 September 2019
+:revdate: 1 September 2023

 
 
 == NAME
 
 
 == NAME


@@ -69,10 +69,12 @@ requires that the input kernel ring buffer lines be sorted by timestamp
 
 == INITIALIZATION PARAMETERS
 
 
 == INITIALIZATION PARAMETERS
 

-param:no-extract-timestamp=`yes` vtype:[optional boolean]::
-    Do :not: extract timestamps from the kernel ring buffer lines: set
-    the created event's payload's `str` field to the whole line,
-    including any timestamp prefix.
+param:no-extract-timestamp='VAL' vtype:[optional boolean]::
+    If 'VAL' is true, then do :not: extract timestamps from the kernel
+    ring buffer lines: set the created event's payload's `str` field to
+    the whole line, including any timestamp prefix.
++
+Default: false.

 
 param:path='PATH' vtype:[optional string]::
     Read the kernel ring buffer lines from the file 'PATH' instead of
 
 param:path='PATH' vtype:[optional string]::
     Read the kernel ring buffer lines from the file 'PATH' instead of