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
40 files changed:
This page took 0.030976 seconds and 4 git commands to generate.