From 7d2597248dc33f15e91305f2b48fd27f1db090b4 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 14 Jun 2021 13:05:37 -0400 Subject: [PATCH] doc/man: use double quotes when referring to internal section MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit This patch adds double quotes to all the manual page internal section references using their full name. Those references often have the following AsciiDoc form: See the <> section below. With this patch, this would be converted to: See the ``<>'' section below. In the rendered manual page, before this patch: See the Full section name section below. ¯¯¯¯ ¯¯¯¯¯¯¯ ¯¯¯¯ With this patch: See the “Full section name” section below. The purpose of this patch is, thanks to the change in `doc/man/manpage.xsl`, to remove the italic style for the text of internal links. Because there's no way to create dynamic internal links in a manual page, this style causes internal links to look weird when they're not a full section name, for example: Note that the trigger doesn't need to [...] ¯¯¯¯¯¯¯ The HTML rendering of LTTng-tools manual pages can still benefit from internal links. This patch makes it possible to add more internal links without degrading the visual style of manual pages when rendered in a terminal. Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau Change-Id: I1a5ef7eab7ff1e66c137e16b51a9c9074e43f583 --- doc/man/common-daemon-cfg.txt | 2 +- doc/man/lttng-add-context.1.txt | 2 +- doc/man/lttng-add-trigger.1.txt | 18 ++-- doc/man/lttng-clear.1.txt | 2 +- doc/man/lttng-concepts.7.txt | 138 ++++++++++++++------------- doc/man/lttng-create.1.txt | 32 +++---- doc/man/lttng-destroy.1.txt | 2 +- doc/man/lttng-disable-channel.1.txt | 2 +- doc/man/lttng-disable-event.1.txt | 2 +- doc/man/lttng-disable-rotation.1.txt | 2 +- doc/man/lttng-enable-channel.1.txt | 2 +- doc/man/lttng-enable-event.1.txt | 50 +++++----- doc/man/lttng-enable-rotation.1.txt | 2 +- doc/man/lttng-event-rule.7.txt | 28 +++--- doc/man/lttng-list.1.txt | 2 +- doc/man/lttng-load.1.txt | 2 +- doc/man/lttng-regenerate.1.txt | 2 +- doc/man/lttng-relayd.8.txt | 12 +-- doc/man/lttng-remove-trigger.1.txt | 2 +- doc/man/lttng-rotate.1.txt | 2 +- doc/man/lttng-save.1.txt | 2 +- doc/man/lttng-sessiond.8.txt | 17 ++-- doc/man/lttng-snapshot.1.txt | 6 +- doc/man/lttng-start.1.txt | 2 +- doc/man/lttng-stop.1.txt | 2 +- doc/man/lttng-track.1.txt | 2 +- doc/man/lttng-untrack.1.txt | 2 +- doc/man/lttng-view.1.txt | 2 +- doc/man/lttng.1.txt | 2 +- doc/man/manpage.xsl | 3 - 30 files changed, 175 insertions(+), 171 deletions(-) diff --git a/doc/man/common-daemon-cfg.txt b/doc/man/common-daemon-cfg.txt index c7b7eed80..ec876736a 100644 --- a/doc/man/common-daemon-cfg.txt +++ b/doc/man/common-daemon-cfg.txt @@ -21,7 +21,7 @@ under the +{daemon-ini-section}+ INI section. Each INI property is: Key:: The long name of a command-line option to set (see the - <> section below). + ``<>'' section below). Value:: The selected command-line option accepts an argument::: diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index 8e5c2bf64..38b77617e 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -112,7 +112,7 @@ NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields to be recorded to the event records of a given channel once its tracing session has been started (see man:lttng-start(1)) at least once. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt index 3454dc8e2..092163cfc 100644 --- a/doc/man/lttng-add-trigger.1.txt +++ b/doc/man/lttng-add-trigger.1.txt @@ -35,7 +35,7 @@ specifier>> and its actions with one or more <>. The order of the action specifiers is significant: LTTng attempts to execute the actions of a firing trigger in this order. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. List the triggers of your Unix user, or of all users if your Unix user is `root`, with the man:lttng-list-triggers(1) command. @@ -71,11 +71,11 @@ See man:lttng-event-rule(7) to learn how to specify an event rule ('ERSPEC' part). + Capture event record and context fields with one or more -nloption:--capture options (see the <> -section below to learn more). When an `event-rule-matches` condition -with capture descriptors is satisfied, the captured field values are -available in the evaluation object of the condition using the -liblttng-ctl C{nbsp}API. +nloption:--capture options (see the ``<>'' section below to learn more). When an +`event-rule-matches` condition with capture descriptors is satisfied, +the captured field values are available in the evaluation object of the +condition using the liblttng-ctl C{nbsp}API. + IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the `add-trigger` command from a shell, as capture descriptors can include @@ -294,12 +294,14 @@ Specifier option:--condition='CONDTYPE':: Introductory option for a condition specifier of type 'CONDTYPE'. + -See the <> section above to learn more. +See the ``<>'' section above to learn +more. option:--action='ACTTYPE':: Introductory option for an action specifier of type 'ACTTYPE'. + -See the <> section above to learn more. +See the ``<>'' section above to learn +more. include::common-lttng-cmd-help-options.txt[] diff --git a/doc/man/lttng-clear.1.txt b/doc/man/lttng-clear.1.txt index a74bee0ed..e2b878cf3 100644 --- a/doc/man/lttng-clear.1.txt +++ b/doc/man/lttng-clear.1.txt @@ -54,7 +54,7 @@ man:lttng-relayd(8) can disable remote clearing operations. If LTTng sends tracing data over the network for the selected tracing session(s) to an LTTng relay daemon configured as such, the `clear` command fails. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-concepts.7.txt b/doc/man/lttng-concepts.7.txt index e4259f9d1..463d957e2 100644 --- a/doc/man/lttng-concepts.7.txt +++ b/doc/man/lttng-concepts.7.txt @@ -38,8 +38,8 @@ An _instrumentation point_ is a point, within a piece of software, which, when executed, creates an LTTng _event_. LTTng offers various types of instrumentation; see the -<> section below to learn -about them. +``<>'' section below to +learn about them. An _event rule_ is a set of conditions to match a set of events. @@ -61,27 +61,27 @@ The actual creation of an event can be costly because LTTng needs to evaluate the arguments of the instrumentation point. In practice, LTTng implements various optimizations for the Linux kernel -and user space tracing domains (see the <> section -below) to avoid actually creating an event -when the tracer knows, thanks to properties which are independent from -the event payload and current context, that it would never emit such an -event. Those properties are: +and user space tracing domains (see the ``<>'' +section below) to avoid actually creating an event when the tracer +knows, thanks to properties which are independent from the event payload +and current context, that it would never emit such an event. Those +properties are: * The instrumentation point type (see the - <> section below). + ``<>'' section below). * The instrumentation point name. * The instrumentation point log level. * For a recording event rule (see the - <> section + ``<>'' section below): ** The status of the rule itself. -** The status of the channel (see the <> section - below). +** The status of the channel (see the ``<>'' + section below). ** The activity of the tracing session (started or stopped; see - the <> section below). + the ``<>'' section below). ** Whether or not the process for which LTTng would create the event is allowed to record events (see man:lttng-track(1)). @@ -98,7 +98,7 @@ Recording event rule:: A specific type of event rule of which the action is to record the matched event as an event record. + -See the <> section +See the ``<>'' section below. + Create or enable a recording event rule with the @@ -121,7 +121,8 @@ basic conditions of an event rule{nbsp}__ER__, that is: * The instrumentation point from which LTTng creates{nbsp}__E__ has a specific type. + -See the <> section below. +See the ``<>'' section +below. * A pattern matches the name of{nbsp}__E__ while another pattern doesn't. @@ -134,7 +135,7 @@ See the <> section below. satisfy a filter expression. A recording event rule has additional, implicit conditions to satisfy. -See the <> section +See the ``<>'' section below to learn more. @@ -143,7 +144,7 @@ Instrumentation point types ~~~~~~~~~~~~~~~~~~~~~~~~~~~ As of LTTng{nbsp}{lttng_version}, the available instrumentation point types are, depending on the tracing domain (see the -<> section below): +``<>'' section below): Linux kernel:: LTTng tracepoint::: @@ -223,17 +224,17 @@ actions are: Conditions:: + * The consumed buffer size of a given tracing - session (see the <> section below) + session (see the ``<>'' section below) becomes greater than some value. * The buffer usage of a given channel (see the - <> section below) becomes greater than some - value. + ``<>'' section below) becomes greater than + some value. * The buffer usage of a given channel becomes less than some value. * There's an ongoing tracing session rotation (see the - <> section below). + ``<>'' section below). * A tracing session rotation becomes completed. @@ -292,15 +293,15 @@ happens within a tracing session. In particular, a tracing session: * Has its own state of activity (started or stopped). + An active tracing session is an implicit recording event rule condition -(see the <> section -below). +(see the ``<>'' +section below). * Has its own mode (local, network streaming, snapshot, or live). + -See the <> section below to learn -more. +See the ``<>'' section below to +learn more. -* Has its own channels (see the <> section +* Has its own channels (see the ``<>'' section below) to which are attached their own recording event rules. * Has its own process attribute inclusion sets (see man:lttng-track(1)). @@ -393,7 +394,7 @@ Snapshot mode:: listening relay daemon (man:lttng-relayd(8)) when LTTng takes a snapshot. + -LTTng forces all the channels (see the <> +LTTng forces all the channels (see the ``<>'' section below) to be created to be configured to be snapshot-ready. + LTTng takes a snapshot of such a tracing session when: @@ -402,7 +403,7 @@ LTTng takes a snapshot of such a tracing session when: * You run the man:lttng-snapshot(1) command. * LTTng executes a `snapshot-session` trigger action (see the - <> section above). + ``<>'' section above). -- Live mode:: @@ -425,7 +426,7 @@ can read it, modify it, move it, or remove it. An _archived trace chunk_ is a collection of metadata and data stream files which form a self-contained LTTng trace. See the -<> section below to learn how +``<>'' section below to learn how LTTng names a trace chunk archive directory. The _current trace chunk_ of a given tracing session includes: @@ -436,7 +437,7 @@ The _current trace chunk_ of a given tracing session includes: ** The first time the tracing session was started, either with the man:lttng-start(1) command or with a `start-session` trigger action - (see the <> section above). + (see the ``<>'' section above). ** The last rotation, performed with: @@ -446,7 +447,7 @@ The _current trace chunk_ of a given tracing session includes: man:lttng-enable-rotation(1). *** An executed `rotate-session` trigger action (see the - <> section above). + ``<>'' section above). * The content of all the non-flushed sub-buffers of the channels of the tracing session. @@ -546,11 +547,11 @@ You must specify a tracing domain to target a type of LTTng tracer when using some man:lttng(1) commands to avoid ambiguity. For example, because the Linux kernel and user space tracing domains support named tracepoints as instrumentation points (see the -<<"event-rule","{sect-event-rule}">> section above), you need to specify -a tracing domain when you create an event rule because both tracing -domains could have tracepoints sharing the same name. +``<<"event-rule","{sect-event-rule}">>'' section above), you need to +specify a tracing domain when you create an event rule because both +tracing domains could have tracepoints sharing the same name. -You can create channels (see the <> section +You can create channels (see the ``<>'' section below) in the Linux kernel and user space tracing domains. The other tracing domains have a single, default channel. @@ -562,7 +563,7 @@ A _channel_ is an object which is responsible for a set of ring buffers. Each ring buffer is divided into multiple _sub-buffers_. When a recording event rule (see the -<>'' section below) matches an event, LTTng can record it to one or more sub-buffers of one or more channels. @@ -571,28 +572,29 @@ you set its final attributes, that is: * Its buffering scheme. + -See the <> section below. +See the ``<>'' section below. * What to do when there's no space left for a new event record because all sub-buffers are full. + -See the <> section below. +See the ``<>'' section +below. * The size of each ring buffer and how many sub-buffers a ring buffer has. + -See the <> section -below. +See the ``<>'' +section below. * The size of each trace file LTTng writes for this channel and the maximum count of trace files. + -See the <> section below. +See the ``<>'' section below. * The periods of its read, switch, and monitor timers. + -See the <> section below. +See the ``<>'' section below. * For a Linux kernel channel: its output type (man:mmap(2) or man:splice(2)). @@ -610,9 +612,9 @@ a default channel with sane defaults when no channel exists for the provided tracing domain. A channel is always associated to a tracing domain (see the -<> section below). The `java.util.logging` (JUL), -log4j, and Python tracing domains each have a default channel which you -can't configure. +``<>'' section below). The `java.util.logging` +(JUL), log4j, and Python tracing domains each have a default channel +which you can't configure. A channel owns recording event rules. @@ -716,8 +718,8 @@ similar to the roll mode of an oscilloscope. + Since LTTng{nbsp}2.8, with this mode, LTTng writes to a given sub-buffer its sequence number within its data stream. With a local, network -streaming, or live tracing session (see the <> section above), a trace reader can use such sequence +streaming, or live tracing session (see the ``<>'' section above), a trace reader can use such sequence numbers to report lost packets. A trace reader can use the saved discarded sub-buffer (packet) count of the trace to decide whether or not to perform some analysis even if trace data is known to be missing. @@ -738,10 +740,10 @@ and nloption:--overwrite options of the man:lttng-enable-channel(1) command. There are a few ways to decrease your probability of losing event -records. The <> -section below shows how to fine-tune the sub-buffer size and count of a -channel to virtually stop losing event records, though at the cost of -greater memory usage. +records. The ``<>'' section below shows how to fine-tune the sub-buffer size and +count of a channel to virtually stop losing event records, though at the +cost of greater memory usage. [[channel-sub-buf-size-count]] @@ -749,8 +751,8 @@ Sub-buffer size and count ~~~~~~~~~~~~~~~~~~~~~~~~~ A channel has one or more ring buffer for each CPU of the target system. -See the <> section above to learn -how many ring buffers of a given channel are dedicated to each CPU +See the ``<>'' section above to +learn how many ring buffers of a given channel are dedicated to each CPU depending on its buffering scheme. Set the size of each sub-buffer the ring buffers of a channel contain @@ -772,12 +774,12 @@ High event throughput:: event records. + Having larger sub-buffers also ensures a lower sub-buffer switching -frequency (see the <> section below). +frequency (see the ``<>'' section below). + The sub-buffer count is only meaningful if you create the channel in -overwrite mode (see the <> -section above): in this case, if LTTng overwrites a sub-buffer, then the -other sub-buffers are left unaltered. +overwrite mode (see the ``<>'' section above): in this case, if LTTng overwrites a sub-buffer, +then the other sub-buffers are left unaltered. Low event throughput:: In general, prefer smaller sub-buffers since the risk of losing @@ -850,8 +852,8 @@ trace file open with the trace file rotation feature. The only way to obtain an unmanaged, self-contained LTTng trace before you destroy the tracing session is with the tracing session rotation -feature (see the <> section above), -which is available since LTTng{nbsp}2.11. +feature (see the ``<>'' section +above), which is available since LTTng{nbsp}2.11. ==== @@ -871,9 +873,9 @@ data to trace files or to a distant relay daemon (man:lttng-relayd(8)) periodically in case of a low event throughput. + Such a timer is also convenient when you use large sub-buffers (see the -<> section above) -to cope with a sporadic high event throughput, even if the throughput is -otherwise low. +``<>'' section +above) to cope with a sporadic high event throughput, even if the +throughput is otherwise low. + Set the period of the switch timer of a channel, or disable the timer altogether, with the nloption:--switch-timer option of the @@ -915,7 +917,8 @@ If you disable the monitor timer of a channel{nbsp}__C__: for{nbsp}__C__ will never be satisfied. -- + -See the <> section above to learn more about triggers. +See the ``<>'' section above to learn more about +triggers. + Set the period of the monitor timer of a channel, or disable the timer altogether, with the nloption:--monitor-timer option of the @@ -926,8 +929,9 @@ man:lttng-enable-channel(1) command. {sect-recording-event-rule} --------------------------- A _recording event rule_ is a specific type of event rule (see the -<<"event-rule","{sect-event-rule}">> section above) of which the action is -to serialize and record the matched event as an _event record_. +``<<"event-rule","{sect-event-rule}">>'' section above) of which the +action is to serialize and record the matched event as an _event +record_. Set the explicit conditions of a recording event rule when you create it with the man:lttng-enable-event(1) command. A recording event rule also @@ -941,13 +945,13 @@ A recording event rule is enabled on creation. + A channel is enabled on creation. + -See the <> section above. +See the ``<>'' section above. * The tracing session of the recording event rule is active (started). + A tracing session is inactive (stopped) on creation. + -See the <> section above. +See the ``<>'' section above. * The process for which LTTng creates an event to match is allowed to record events. diff --git a/doc/man/lttng-create.1.txt b/doc/man/lttng-create.1.txt index a1bf9d80e..4e997e1d1 100644 --- a/doc/man/lttng-create.1.txt +++ b/doc/man/lttng-create.1.txt @@ -91,7 +91,7 @@ genoption:--relayd-path option. On success, the `create` command sets the current tracing session (see man:lttng-concepts(7) to learn more) to the created tracing session. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. Show the status of the current tracing session with the man:lttng-status(1) command. @@ -143,7 +143,7 @@ Otherwise::: + Set the trace output destination with the option:--set-url option, or with the option:--ctrl-url and option:--data-url options (see the -<> section below). +``<>'' section below). [[snapshot-mode]]Snapshot mode (option:--snapshot option):: Only write the trace data to the local file system or send it to a @@ -175,8 +175,8 @@ date/time. + Set the trace output destination with the option:--set-url='URL' option, or with the option:--ctrl-url='URL' and option:--data-url='URL' options -(see the <> section below). 'URL' may :not: start -with `file://`. +(see the ``<>'' section below). 'URL' may :not: +start with `file://`. [[url-format]] @@ -195,8 +195,8 @@ file://'TRACEDIR' + The `file://` protocol targets the *local file system*: you may only use such an URL with the option:--set-url option when you create the tracing -session in local or snapshot mode (see the <> section above). +session in local or snapshot mode (see the ``<>'' section above). + 'TRACEDIR'::: Absolute path to the directory containing the trace data on the @@ -210,7 +210,7 @@ Network format:: + This format is only available when you create the tracing session in network streaming, snapshot (option:--snapshot), or live (option:--live) -mode (see the <> section above). +mode (see the ``<>'' section above). + 'NETPROTO'::: Network protocol, amongst: @@ -268,7 +268,7 @@ include::common-lttng-cmd-options-head.txt[] Mode selection ~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. At most one of: @@ -320,8 +320,8 @@ date/time. Output ~~~~~~ option:--no-output:: - Depending on the tracing session mode (see the <> section above): + Depending on the tracing session mode (see the ``<>'' section above): + Local mode::: Disable the file system output. @@ -339,15 +339,15 @@ option:--shm-path='DIR':: URL ~~~ -See the <> section above to learn more about the -syntax of the 'URL' argument of the following options. +See the ``<>'' section above to learn more about +the syntax of the 'URL' argument of the following options. option:-C 'URL', option:--ctrl-url='URL':: Set the control path URL to 'URL'. + You must also use the option:--data-url option. + -Not available in local mode (see the <> +Not available in local mode (see the ``<>'' section above). + In snapshot mode, this is equivalent to using the nloption:--ctrl-url @@ -359,7 +359,7 @@ option:-D 'URL', option:--data-url='URL':: + You must also use the option:--ctrl-url option. + -Not available in local mode (see the <> +Not available in local mode (see the ``<>'' section above). + In snapshot mode, this is equivalent to using the nloption:--data-url @@ -371,8 +371,8 @@ option:-U 'URL', option:--set-url='URL':: + This URL remains unchanged as long as the tracing session exists. + -Depending on the tracing session mode (see the <> section above): +Depending on the tracing session mode (see the ``<>'' section above): + Local mode::: 'URL' must start with `file://`, followed with the destination diff --git a/doc/man/lttng-destroy.1.txt b/doc/man/lttng-destroy.1.txt index 7ab13a7f6..048809a52 100644 --- a/doc/man/lttng-destroy.1.txt +++ b/doc/man/lttng-destroy.1.txt @@ -64,7 +64,7 @@ Then all the subdirectories of the output directory of{nbsp}__TS__ command exits. In other words, it's safe to read them, modify them, move them, or remove then. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-disable-channel.1.txt b/doc/man/lttng-disable-channel.1.txt index 21e7e6c93..60ad93647 100644 --- a/doc/man/lttng-disable-channel.1.txt +++ b/doc/man/lttng-disable-channel.1.txt @@ -36,7 +36,7 @@ As of LTTng{nbsp}{lttng_version}, you may :not: enable a disabled channel once its tracing session has been started (see man:lttng-start(1)) at least once. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-disable-event.1.txt b/doc/man/lttng-disable-event.1.txt index 9afa53c1b..710e6d9dc 100644 --- a/doc/man/lttng-disable-event.1.txt +++ b/doc/man/lttng-disable-event.1.txt @@ -77,7 +77,7 @@ You may disable an enabled recording event rule regardless of the activity (started or stopped) of its tracing session (see man:lttng-start(1) and man:lttng-stop(1)). -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-disable-rotation.1.txt b/doc/man/lttng-disable-rotation.1.txt index c28d699d2..b088c94f2 100644 --- a/doc/man/lttng-disable-rotation.1.txt +++ b/doc/man/lttng-disable-rotation.1.txt @@ -30,7 +30,7 @@ Without the option:--session option:: See man:lttng-concepts(7) to learn more about the tracing session rotation and trace chunk concepts. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt index 6c1091ec1..2428c8a96 100644 --- a/doc/man/lttng-enable-channel.1.txt +++ b/doc/man/lttng-enable-channel.1.txt @@ -63,7 +63,7 @@ Without the option:--session option:: NOTE: The man:lttng-enable-event(1) command can automatically create a default channel when no channel exists for the provided tracing domain. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. List the channels of a given tracing session with the man:lttng-list(1) and man:lttng-status(1) commands. diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 433fa2341..2a8289697 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -52,7 +52,7 @@ The `lttng enable-event` command does one of: * Enable one or more disabled recording event rules. + -See the <> section +See the ``<>'' section below. See man:lttng-concepts(7) to learn more about instrumentation points, @@ -77,7 +77,7 @@ If there's already a channel for the selected tracing session and domain which isn't named `channel0`, the `enable-event` command fails. Otherwise, it automatically creates it. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. List the recording event rules of a specific tracing session and/or channel with the man:lttng-list(1) and man:lttng-status(1) @@ -101,25 +101,25 @@ Explicit conditions:: * The instrumentation point type from which LTTng creates{nbsp}__E__ has a specific type. + -See the <> -section below. +See the ``<>'' section below. * A pattern matches the name of{nbsp}__E__ while another pattern doesn't. + -See the <> section below. +See the ``<>'' section below. * The log level of the instrumentation point from which LTTng creates{nbsp}__E__ is at least as severe as some value, or is exactly some value. + -See the <> -section below. +See the ``<>'' section below. * The fields of the payload of{nbsp}__E__ and the current context fields satisfy a filter expression. + -See the <> +See the ``<>'' section below. -- @@ -193,7 +193,7 @@ List the available Linux kernel system call instrumentation points with The argument of the option:--probe option is the location of the kprobe to insert, either a symbol or a memory address, while 'RECORDNAME' is the name of the record -of{nbsp}__E__ (see the <> section below). +of{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux kprobe event is empty. @@ -215,7 +215,7 @@ are :not: reference-counted. -- + 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the -<> section below). +``<>'' section below). + The payload of a Linux user space probe event is empty. @@ -226,7 +226,7 @@ The payload of a Linux user space probe event is empty. The argument of the option:--function option is the location of the Linux kretprobe to insert, either a symbol or a memory address, while 'RECORDNAME' is the name of the record -of{nbsp}__E__ (see the <> section below). +of{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux kretprobe event is empty. @@ -264,8 +264,8 @@ event rule{nbsp}__ER__ if the two following statements are true: * You specify the option:--all option or, depending on the instrumentation type condition (see the - <> section - above) of{nbsp}__ER__, 'NAME' matches: + ``<>'' + section above) of{nbsp}__ER__, 'NAME' matches: + -- LTTng tracepoint:: @@ -553,8 +553,8 @@ Event record name ~~~~~~~~~~~~~~~~~ When LTTng records an event{nbsp}__E__, the resulting event record has a name which depends on the instrumentation point type condition (see the -<> section -above) of the recording event rule which matched{nbsp}__E__: +``<>'' +section above) of the recording event rule which matched{nbsp}__E__: LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options):: Full name of the tracepoint from which LTTng creates{nbsp}__E__. @@ -661,8 +661,8 @@ option:-s 'SESSION', option:--session='SESSION':: Instrumentation point type condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> -section above. +See the ``<>'' section above. At most one of: @@ -681,7 +681,7 @@ Only available with the option:--kernel option. -- + You must specify the event record name with 'RECORDNAME'. See the -<> section above to learn more. +``<>'' section above to learn more. option:--probe='LOC':: Only match Linux kprobe events. @@ -697,7 +697,7 @@ Only available with the option:--kernel option. -- + You must specify the event record name with 'RECORDNAME'. See the -<> section above to learn more. +``<>'' section above to learn more. option:--userspace-probe='LOC':: Only match Linux user space probe events. @@ -773,7 +773,7 @@ Example: `--userspace-probe=sdt:./build/server:server:accept_request` -- + You must specify the event record name with 'RECORDNAME'. See the -<> section above to learn more. +``<>'' section above to learn more. option:--syscall:: Only match Linux system call events. @@ -800,7 +800,7 @@ future. Event name condition ~~~~~~~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. option:-a, option:--all:: Equivalent to a single 'NAME' argument (LTTng tracepoint or logger @@ -821,8 +821,8 @@ a literal `,` character, use :esccomma:. Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. At most one of: @@ -840,7 +840,7 @@ with the option:--kernel option. Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> +See the ``<>'' section above. option:-f 'EXPR', option:--filter='EXPR':: @@ -904,7 +904,7 @@ $ lttng enable-event --log4j --channel=my-loggers \ ==== The recording event rule below matches the entry of `usb_disconnect()` Linux kernel function calls. The records of such events are named `usbd` -(see the <> section above). +(see the ``<>'' section above). See the option:--probe option. diff --git a/doc/man/lttng-enable-rotation.1.txt b/doc/man/lttng-enable-rotation.1.txt index 2071848e1..a607a5739 100644 --- a/doc/man/lttng-enable-rotation.1.txt +++ b/doc/man/lttng-enable-rotation.1.txt @@ -60,7 +60,7 @@ You may combine the option:--timer and option:--size options. See the man:lttng-concepts(7) to learn how LTTng names a trace chunk archive directory. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. Unset a tracing session rotation schedule with the man:lttng-disable-rotation(1) command. diff --git a/doc/man/lttng-event-rule.7.txt b/doc/man/lttng-event-rule.7.txt index b2169a162..493ed6a29 100644 --- a/doc/man/lttng-event-rule.7.txt +++ b/doc/man/lttng-event-rule.7.txt @@ -69,25 +69,25 @@ conditions of an event rule, that is: * The instrumentation point from which LTTng creates{nbsp}__E__ has a specific type. + -See the <> -section below. +See the ``<>'' section below. * A pattern matches the name of{nbsp}__E__ while another pattern doesn't. + -See the <> section below. +See the ``<>'' section below. * The log level of the instrumentation point from which LTTng creates{nbsp}__E__ is at least as severe as some value, or is exactly some value. + -See the <> section below. +See the ``<>'' section below. * The fields of the payload of{nbsp}__E__ and the current context fields satisfy a filter expression. + -See the <> +See the ``<>'' section below. The dedicated command-line options of most conditions are optional: if @@ -178,8 +178,8 @@ rule{nbsp}__ER__ if the two following statements are true: * You don't specify the option:--name='NAME' option or, depending on the instrumentation type condition (see the - <> section - above) of{nbsp}__ER__, 'NAME' matches: + ``<>'' + section above) of{nbsp}__ER__, 'NAME' matches: + -- `kernel:tracepoint`:: @@ -529,8 +529,8 @@ OPTIONS ------- Instrumentation point type condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> -section above. +See the ``<>'' section above. option:-E 'NAME', option:--event-name='NAME':: With the option:--type=++kernel:kprobe++ or @@ -702,7 +702,7 @@ change in the future. Event name condition ~~~~~~~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. option:-n 'NAME', option:--name='NAME':: Only match events of which 'NAME' matches, depending on the @@ -742,8 +742,8 @@ Only available with the option:--type=++user:tracepoint++ option. Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. option:-l 'LOGLEVELSPEC', option:--log-level='LOGLEVELSPEC':: Only match events of which the log level of the LTTng tracepoint or @@ -776,7 +776,7 @@ but this default may change in the future. Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> +See the ``<>'' section above. option:-f 'EXPR', option:--filter='EXPR':: diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index 7256f4a9a..12b137697 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -87,7 +87,7 @@ option:--fields option. See man:lttng-concept(7) to learn more about tracing sessions, tracing domains, channels, recording event rules, and instrumentation points. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. List the channels and recording event rules of the current tracing session (see man:lttng-concept(7) to learn more) with the diff --git a/doc/man/lttng-load.1.txt b/doc/man/lttng-load.1.txt index bebe12306..4a0ffa8f4 100644 --- a/doc/man/lttng-load.1.txt +++ b/doc/man/lttng-load.1.txt @@ -71,7 +71,7 @@ By default, the `load` command does :not: overwrite existing tracing sessions: the command fails. Allow the `load` command to overwrite existing tracing sessions with the option:--force option. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-regenerate.1.txt b/doc/man/lttng-regenerate.1.txt index 7e4476007..b1cdc054c 100644 --- a/doc/man/lttng-regenerate.1.txt +++ b/doc/man/lttng-regenerate.1.txt @@ -37,7 +37,7 @@ See man:lttng-concepts(7) to learn more about tracing sessions. As of this version, the `metadata` and `statedump` targets are available. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. Regenerate the metadata of a tracing session diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt index 90cc1547d..d165d93eb 100644 --- a/doc/man/lttng-relayd.8.txt +++ b/doc/man/lttng-relayd.8.txt @@ -34,7 +34,7 @@ while the remote tracing session is active. By default, a relay daemon listens on all network interfaces to receive trace data, but only on `localhost` for LTTng live connections. Override the listening URLs with the option:--control-port, option:--data-port, -and option:--live-port options (see the <> +and option:--live-port options (see the ``<>'' section below). For example, use the option:--live-port=+tcp://0.0.0.0:{default_network_viewer_port}+ option to make a relay daemon listen to LTTng live connections on all network @@ -70,7 +70,7 @@ The relay daemon uses different output path patterns depending on: * Its configuration. + -See the <> section above. +See the ``<>'' section above. * The tracing session configuration of the connected peer. * The LTTng session daemon (see man:lttng-sessiond(8)) version @@ -180,7 +180,7 @@ option:-f 'PATH', option:--config='PATH':: addition to the default configuration files and the command-line options. + -See the <> section above. +See the ``<>'' section above. option:-d, option:--daemonize:: Start as a Unix daemon and close file descriptors (console). @@ -230,7 +230,7 @@ Specify this option up to three times to get more levels of verbosity. Output ~~~~~~ -See the <> section above to learn +See the ``<>'' section above to learn more. option:-p, option:--group-output-by-host:: @@ -250,8 +250,8 @@ option:-o 'DIR', option:--output='DIR':: Ports ~~~~~ -See the <> section above to learn more about the -syntax of the 'URL' argument of the following options. +See the ``<>'' section above to learn more about +the syntax of the 'URL' argument of the following options. option:-C 'URL', option:--control-port='URL':: Listen to control data on URL 'URL'. diff --git a/doc/man/lttng-remove-trigger.1.txt b/doc/man/lttng-remove-trigger.1.txt index 1f5285d2f..6bec8c555 100644 --- a/doc/man/lttng-remove-trigger.1.txt +++ b/doc/man/lttng-remove-trigger.1.txt @@ -27,7 +27,7 @@ The `remove-trigger` command removes a trigger which belong to your Unix user. If your Unix user is `root`, you can remove the trigger of another user with the option:--owner-uid option. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. OPTIONS diff --git a/doc/man/lttng-rotate.1.txt b/doc/man/lttng-rotate.1.txt index 2a73f8bcf..91df503fe 100644 --- a/doc/man/lttng-rotate.1.txt +++ b/doc/man/lttng-rotate.1.txt @@ -62,7 +62,7 @@ directly cause discarded event records or packets. A `rotate-session` trigger action can also rotate a tracing session (see man:lttng-add-trigger(1)). -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. [IMPORTANT] ==== diff --git a/doc/man/lttng-save.1.txt b/doc/man/lttng-save.1.txt index b9c334592..26e350dbc 100644 --- a/doc/man/lttng-save.1.txt +++ b/doc/man/lttng-save.1.txt @@ -51,7 +51,7 @@ session configuration files: the command fails. Allow the `save` command to overwrite existing tracing session configuration files with the option:--force option. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-sessiond.8.txt b/doc/man/lttng-sessiond.8.txt index 4a8b4b6b2..fe8a9c66d 100644 --- a/doc/man/lttng-sessiond.8.txt +++ b/doc/man/lttng-sessiond.8.txt @@ -143,7 +143,7 @@ option:-f 'PATH', option:--config='PATH':: addition to the default configuration files and the command-line options. + -See the <> section above. +See the ``<>'' section above. option:-d, option:--daemonize:: Start as a Unix daemon and close file descriptors (console). @@ -168,7 +168,8 @@ option:-l 'PATH', option:--load='PATH':: or a file, instead of loading them from the default search directories. + -See the <> section above. +See the ``<>'' section +above. option:-S, option:--sig-parent:: Send the `USR1` signal to the parent process to notify readiness. @@ -398,25 +399,25 @@ man:lttng-create(1) command. Directory from which `lttng-sessiond` loads Unix user tracing session configurations when starting. + -See the <> section above to -learn more. +See the ``<>'' section above +to learn more. +{system_sessions_auto_dir}+:: Directory from which `lttng-sessiond` loads system-wide tracing session configurations when starting. + -See the <> section above to -learn more. +See the ``<>'' section above +to learn more. `$LTTNG_HOME/.lttng/lttng.conf`:: Unix user's LTTng daemon INI configuration file. + -See the <> section above to learn more. +See the ``<>'' section above to learn more. +{system_lttng_conf}+:: System-wide LTTng daemon INI configuration file. + -See the <> section above to learn more. +See the ``<>'' section above to learn more. NOTE: `$LTTNG_HOME` defaults to `$HOME`. diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt index b81adbc9d..7886bbde5 100644 --- a/doc/man/lttng-snapshot.1.txt +++ b/doc/man/lttng-snapshot.1.txt @@ -55,7 +55,7 @@ the selected tracing session. When LTTng takes a snapshot, it sends the sub-buffer dump of the selected tracing session to the local file system or over the network to a listening relay daemon (man:lttng-relayd(8)). See the -<> section below to learn more. +``<>'' section below to learn more. When LTTng takes a snapshot, it does :not: clear the sub-buffers of the selected tracing session. In other words, different snapshots of the @@ -69,7 +69,7 @@ to use the `snapshot` command. A `snapshot-session` trigger action can also take a tracing session snapshot (see man:lttng-add-trigger(1)). -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. If you want, instead, to keep all the trace data, but divide it into archived chunks which are then, like snapshots, ready to be processed, @@ -159,7 +159,7 @@ option:-s 'SESSION', option:--session='SESSION':: Output ~~~~~~ -See the <> section above. +See the ``<>'' section above. option:-C 'URL', option:--ctrl-url='URL':: Set the control path URL to 'URL'. diff --git a/doc/man/lttng-start.1.txt b/doc/man/lttng-start.1.txt index d4f52cbac..0ee764e40 100644 --- a/doc/man/lttng-start.1.txt +++ b/doc/man/lttng-start.1.txt @@ -34,7 +34,7 @@ session is inactive on creation (see man:lttng-create(1)). A `start-session` trigger action can also start a tracing session (see man:lttng-add-trigger(1)). -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. Stop an active tracing session with the man:lttng-stop(1) command. diff --git a/doc/man/lttng-stop.1.txt b/doc/man/lttng-stop.1.txt index d0371c74d..19da7e966 100644 --- a/doc/man/lttng-stop.1.txt +++ b/doc/man/lttng-stop.1.txt @@ -52,7 +52,7 @@ remains inactive, it's :not: a trace chunk archive: you need to destroy the tracing session with man:lttng-destroy(1) or perform a rotation with man:lttng-rotate(1) to archive it. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng-track.1.txt b/doc/man/lttng-track.1.txt index 2a04eeedc..5c328c6e0 100644 --- a/doc/man/lttng-track.1.txt +++ b/doc/man/lttng-track.1.txt @@ -111,7 +111,7 @@ $ lttng track --kernel --pid=2345 $ lttng start ---- -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. Remove values from an inclusion set with the man:lttng-untrack(1) command. diff --git a/doc/man/lttng-untrack.1.txt b/doc/man/lttng-untrack.1.txt index 771c5e69c..e70ef968b 100644 --- a/doc/man/lttng-untrack.1.txt +++ b/doc/man/lttng-untrack.1.txt @@ -52,7 +52,7 @@ recording event rules. The `untrack` command removes values from _inclusion sets_ of process attributes. See man:lttng-track(1) to learn more about inclusion sets. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. Inclusion set example diff --git a/doc/man/lttng-view.1.txt b/doc/man/lttng-view.1.txt index a91e5dff6..0eccb30d1 100644 --- a/doc/man/lttng-view.1.txt +++ b/doc/man/lttng-view.1.txt @@ -38,7 +38,7 @@ By default, the `view` command attempts to launch man:babeltrace2(1) or, if it's not available, man:babeltrace(1). Override which trace reader to launch with the option:--viewer option. -See the <> section below for usage examples. +See the ``<>'' section below for usage examples. include::common-lttng-cmd-options-head.txt[] diff --git a/doc/man/lttng.1.txt b/doc/man/lttng.1.txt index fff757a49..fba24cee5 100644 --- a/doc/man/lttng.1.txt +++ b/doc/man/lttng.1.txt @@ -67,7 +67,7 @@ See man:lttng-concepts(7) to learn more about the foundational concepts of LTTng. The `lttng` tool offers a subcommand-based command-line interface. The -<> section below lists the available commands. +``<>'' section below lists the available commands. Session daemon connection diff --git a/doc/man/manpage.xsl b/doc/man/manpage.xsl index b8f726848..67dff7651 100644 --- a/doc/man/manpage.xsl +++ b/doc/man/manpage.xsl @@ -22,9 +22,6 @@ <> - - \fI\fR - -- 2.34.1