doc/man: lttng(1) command pages: always include `common-footer.txt` The end of an lttng(1) command manual page source now looks like this: include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] include::common-footer.txt[] `common-lttng-cmd-after-options.txt` contains the "EXIT STATUS", "ENVIRONMENT", and "FILES" sections. `common-footer.txt` begins with the "RESOURCES" section. This will make it possible to insert an "EXAMPLES" section between `common-lttng-cmd-after-options.txt` and `common-footer.txt`. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I1eee42d7386f4671d9825e9d3e131e54f868ee39
Update the remaining manual pages for LTTng-tools 2.13 This patch updates the remaining manual pages for LTTng-tools 2.13. This patch: * Improves the consistency of some command descriptions in `configure.ac`. * Adds `common-daemon-cfg.txt` which is a section explaining how to configure a daemon (session or relay). lttng-sessiond(8) and lttng-relayd(8) include this file. * Adds `lttng-concepts.7.txt` which is an adapted copy of the "Core concepts" section of the online LTTng Documentation. This centralizes all the LTTng theory into a single manual page instead of having this information split into multiple lttng(1) command manual pages. Many manual pages now refer to lttng-concepts(7), making it possible to cut a lot of text in those. * Updates existing manual pages to: * Have a style and voice which is more consistent with the LTTng Documentation (website) for 2.13. * Fix various terminology ambiguities. * Use more textual variables and lists to explain more complex logic and processes. * Always use the same pattern to specify the behaviour of an lttng(1) command depending on the `SESSION` argument or the `--session` option. * For the commands which can perform more than one task, list their available tasks at the beginning of the "DESCRIPTION" section. * For some lttng(1) commands which can operate on all tracing sessions (for example, lttng-clear(1) and lttng-destroy(1)), always indicate that they target all your Unix user's tracing sessions or, if your Unix user is `root`, the tracing sessions of all the Unix users within the root session daemon. * Clean the "SEE ALSO" sections. * Always have "LTTng" in the "NAME" section of a manual page. More specifically: lttng-create(1): * Clarify the tracing session modes. * Clarify how the command adds (or not) a snapshot output for a snapshot mode tracing session. * Specify that `--output=DIR` is equivalent to `--set-url=file://DIR`. lttng-enable-channel(1): Include the `--discard`, `--buffers-uid`, and `--buffers-global` options in the "SYNOPSIS" section even if they are the current defaults. lttng-list(1): Explain what this command does exactly using a tree of options and arguments. lttng-load(1): Clarify how LTTng finds tracing session configurations. lttng-relayd(8): * Document the missing `--group` option. * Rework the text in general. * Add a daemon configuration section with an INI file example. * Add more cross-references between options and equivalent environment variables. lttng-rotate(1): Specify that the `rotate-session` trigger action can also rotate a tracing session. lttng-save(1): Clarify the output path. lttng-sessiond(8): Add more cross-references between options and equivalent environment variables. lttng-shapshot(1): * Clarify everything related to the snapshot output of a tracing session, including when and how the lttng-create(1) command adds an initial snapshot output. * Specify that the `snapshot-session` trigger action can also take a snapshot of a tracing session. lttng-track(1): lttng-untrack(1): * Simply refer to allowing processes to record events and to process attribute inclusion sets instead of using the vague "tracker" terminology. * Restate that those commands control an implicit condition of a recording event rule, as per lttng-concepts(7). * Improve the documentation of each inclusion set selection option. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: Iac7498ee979fe077f0927a9b8335f6c07f203989
Update some manual pages for LTTng-tools 2.13 This patch updates some manual pages for LTTng-tools 2.13. A few pages still remain to be updated, a task which is reserved for a subsequent patch. This patch: * Improves the consistency of the the command descriptions in `configure.ac`. * Adds `common-help-option.txt` which is the description of any `--help` option. * Adds `common-intro.txt` which is a common description introduction for the top-level manual pages. * Adds `lttng-event-rule.7.txt` which describes the common way to specify an event rule on the command-line. lttng-event-rule(7) has a "Migration from a recording event rule specification" section with a table which shows the relationship between lttng-enable-event(1) command-line arguments and lttng-event-rule(7) options. As of this patch, only `lttng-add-trigger.1.txt` references it, for the `event-rule-matches` trigger condition. `Makefile.am` is also updated to build and include manual pages of section 7. * Updates existing manual pages to: * Have a style and voice which is more consistent with the LTTng Documentation (website) for 2.13. * Fix various terminology ambiguities. * Use more textual variables and lists to explain more complex logic and processes. More specifically: lttng-add-context(1): Specify that this command adds context fields to be recorded to the event records of one or more channels. In other words, this is a recording-related command. You don't need to use it to access context fields with the filter expression of an event rule, for example. lttng-add-trigger(1): * Update the "NAME" section. * Add internal option links where missing. * Improve the description. Add links to the lttng-remove-trigger(1) and lttng-list-triggers(1) manual pages and explain what those commands are used for. Use "condition specifier" and "action specifier" terms to describe those groups of options. For condition and action specifiers, use localized synopses. For action specifiers, add links to the corresponding LTTng command manual pages. * Document the `--owner-id` option. * Group option descriptions. * Use "name" instead of "ID". * Refer to the new lttng-event-rule(7) manual page. * Remove the "no context field" limitation for `ERSPEC`. * Fix verse blocks nested in lists. lttng-create(1): * Add more documentation about tracing sessions. * Specify that the `create` command can spawn a session daemon. * Add the "Current tracing session" section to explain this concept and where it applies. * Clarify the "URL format" section. lttng-disable-event(1): Explain how this command can only find recording event rules to disable by instrumentation point type and event name condition. lttng-enable-event(1): I more or less completely rewrote this page. The document now clearly explains the related core concepts, shows the explicit and implicit conditions of a recording event rule, has one section for each condition explaining how an event can satisfy it, and more. The synopsis is more accurate. I added an "Event record name" section to indicate what's the name of a matched event depending on the instrumentation point type and some command-line arguments. I also added an "Enable a disabled recording event rule" section to explain how the `enable-event` command enables existing, disabled events. This manual page now documents all the options, even if they're the default, as defaults may change in the future. The new lttng-event-rule(7) manual page is based on this one, but with its own ways to specify event rule conditions. lttng-remove-trigger(1): * Use "name" instead of "ID". * Use `--owner-id` instead of `--user-id`. lttng-sessiond(8): * Explain what an LTTng session daemon does. * Clarify everything related to the tracing group and root session daemon. * Add a "Daemon configuration" section which explains the INI configuration files and the `--config` option. * Make the "Tracing session configuration loading" section (renamed) much more straightforward, with less text. * Specify that the `--daemonize` and `--background` options make `lttng-sessiond` only exit when the daemon is ready to receive client commands. lttng-set-session(1): List which commands rely on the current tracing session concept. lttng(1): * Add a "Session daemon connection" section which shows how the `lttng` tool (or any LTTng tracing control application) connects to a session daemon (user-specific vs. root session daemon). * Use tables to list the available commands. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I6b98f4907d94763f3bfcb6576e4add9cfc59a2e3
doc/man: use specific revision date for each manual page This patch makes each manual page indicate its own revision date with the `revdate` AsciiDoc attribute. In `asciidoc.conf`, we use this attribute to specify the DocBook reference page date (see <https://tdg.docbook.org/tdg/4.5/refentryinfo.html> and <https://tdg.docbook.org/tdg/4.5/date.html>). Without the DocBook date tag, `xmlto` uses the current date. You can see this date at the bottom of the rendered manual page: ... SEE ALSO lttng-enable-rotation(1), lttng-disable-rotation(1), lttng(1) LTTng 2.12.0-pre 10/18/2019 LTTNG-ROTATE(1) Using the manual page generation date seems unexpected for the reader here. For this initial change, I used the last commit date for each source file. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
doc/man: add typical `$` and `#` prompts to command lines It is more instinctive for the typical reader to immediately recognize command lines when they start with the classic prompts. On the online version of the man pages, those prompts are treated specially to make them non-selectable. This makes it possible to copy multiple command lines at once (without copying the prompts) and to paste them to your shell. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
doc/man: linklttng macro -> man macro This macro is shorter, and some referenced man pages are not LTTng man pages, so the linklttng name makes little sense. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
doc/man: add [role="term"] to terminal callouts This does not change the troff output, but it annotates the given callouts in the DocBook output so that a DocBook->HTML stylesheet can use this role to visually differentiate terminal callouts from generic callouts. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>