Update some manual pages for LTTng-tools 2.13
authorPhilippe Proulx <eeppeliteloop@gmail.com>
Wed, 3 Mar 2021 20:18:30 +0000 (15:18 -0500)
committerJérémie Galarneau <jeremie.galarneau@efficios.com>
Fri, 23 Apr 2021 21:01:19 +0000 (17:01 -0400)
commit484b2a0cbefcf0c7072622a5a411ea5ed849da28
treeb5a22c9be1b93d86f9d74aae2f66fa7f58038b04
parent574d2e89b608d9f8d42956ec9651fc6bd62a6d8f
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:
.gitignore
configure.ac
doc/man/Makefile.am
doc/man/asciidoc-attrs.conf.in
doc/man/common-cmd-footer.txt
doc/man/common-cmd-help-options.txt
doc/man/common-cmd-options-head.txt
doc/man/common-help-option.txt [new file with mode: 0644]
doc/man/common-intro.txt [new file with mode: 0644]
doc/man/lttng-add-context.1.txt
doc/man/lttng-add-trigger.1.txt
doc/man/lttng-clear.1.txt
doc/man/lttng-crash.1.txt
doc/man/lttng-create.1.txt
doc/man/lttng-destroy.1.txt
doc/man/lttng-disable-channel.1.txt
doc/man/lttng-disable-event.1.txt
doc/man/lttng-disable-rotation.1.txt
doc/man/lttng-enable-channel.1.txt
doc/man/lttng-enable-event.1.txt
doc/man/lttng-enable-rotation.1.txt
doc/man/lttng-event-rule.7.txt [new file with mode: 0644]
doc/man/lttng-help.1.txt
doc/man/lttng-list-triggers.1.txt
doc/man/lttng-list.1.txt
doc/man/lttng-load.1.txt
doc/man/lttng-relayd.8.txt
doc/man/lttng-remove-trigger.1.txt
doc/man/lttng-save.1.txt
doc/man/lttng-sessiond.8.txt
doc/man/lttng-set-session.1.txt
doc/man/lttng-start.1.txt
doc/man/lttng-status.1.txt
doc/man/lttng-stop.1.txt
doc/man/lttng-track.1.txt
doc/man/lttng-version.1.txt
doc/man/lttng-view.1.txt
doc/man/lttng.1.txt
src/bin/lttng/commands/list.c
src/bin/lttng/lttng.c
This page took 0.034116 seconds and 5 git commands to generate.