From 75daa1081c5cfee4197203dc826f30f58174fbac Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Fri, 1 Sep 2023 14:17:28 -0400 Subject: [PATCH] doc/man: make default values of boolean init. params. clearer This patch answers to , 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 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 --- ...trace2-filter.lttng-utils.debug-info.7.txt | 12 +- .../babeltrace2-filter.utils.trimmer.7.txt | 10 +- doc/man/babeltrace2-sink.ctf.fs.7.txt | 28 ++- doc/man/babeltrace2-sink.text.details.7.txt | 44 ++-- doc/man/babeltrace2-sink.text.pretty.7.txt | 212 +++++++++++++++--- doc/man/babeltrace2-sink.utils.counter.7.txt | 9 +- doc/man/babeltrace2-source.ctf.fs.7.txt | 11 +- doc/man/babeltrace2-source.text.dmesg.7.txt | 12 +- 8 files changed, 264 insertions(+), 74 deletions(-) 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 f98c7d7c..bccd8549 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 :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}. -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 diff --git a/doc/man/babeltrace2-filter.utils.trimmer.7.txt b/doc/man/babeltrace2-filter.utils.trimmer.7.txt index b1f754e5..707aac6c 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == 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. -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 diff --git a/doc/man/babeltrace2-sink.ctf.fs.7.txt b/doc/man/babeltrace2-sink.ctf.fs.7.txt index df913414..73660277 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == NAME @@ -194,18 +194,24 @@ until the path does not exist. == 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 <>). ++ +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. @@ -213,8 +219,10 @@ param:path='PATH' vtype:[string]:: See <> 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 diff --git a/doc/man/babeltrace2-sink.text.details.7.txt b/doc/man/babeltrace2-sink.text.details.7.txt index dc879219..8a23dd4e 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == NAME @@ -113,8 +113,8 @@ param:color=(`never` | `auto` | `always`) vtype:[optional string]:: 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, @@ -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. ++ +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 diff --git a/doc/man/babeltrace2-sink.text.pretty.7.txt b/doc/man/babeltrace2-sink.text.pretty.7.txt index 6d0cd292..49687911 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == NAME @@ -43,20 +43,28 @@ man:babeltrace(1) (Babeltrace~1 command-line tool). == 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: @@ -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-`. -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. ++ +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. ++ +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. ++ +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. ++ +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. ++ +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. ++ +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. ++ +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-header=(`yes` | `no`) vtype:[optional boolean]:: +param:name-header='VAL' vtype:[optional boolean]:: 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. ++ +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. ++ +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: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 diff --git a/doc/man/babeltrace2-sink.utils.counter.7.txt b/doc/man/babeltrace2-sink.utils.counter.7.txt index 60f051d5..082750a0 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == NAME @@ -54,8 +54,11 @@ the zero counts with the param:hide-zero parameter. == 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 diff --git a/doc/man/babeltrace2-source.ctf.fs.7.txt b/doc/man/babeltrace2-source.ctf.fs.7.txt index fe3ff322..15ab96e4 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == 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. -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'. diff --git a/doc/man/babeltrace2-source.text.dmesg.7.txt b/doc/man/babeltrace2-source.text.dmesg.7.txt index 9079fe4b..1e75c9d2 100644 --- 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 -:revdate: 14 September 2019 +:revdate: 1 September 2023 == NAME @@ -69,10 +69,12 @@ requires that the input kernel ring buffer lines be sorted by timestamp == 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 -- 2.34.1