From: Philippe Proulx Date: Mon, 14 Jun 2021 17:05:37 +0000 (-0400) Subject: doc/man: use double quotes when referring to internal section X-Git-Url: http://git.efficios.com/?p=lttng-tools.git;a=commitdiff_plain;h=7d2597248dc33f15e91305f2b48fd27f1db090b4 doc/man: use double quotes when referring to internal section 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 --- 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 -