lttng-enable-event.1.txt: uprobe: update style and content

* Better inline styles for option variables.
* Option descriptions moved to the OPTIONS section.
* Expand SDT acronym.
* Add note indicating that SDT probes surrounded by reference counts
  are not supported.
* Use "application" and "library" instead of "executable".

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Reviewed-by: Francis Deslauriers <francis.deslauriers@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt
index 3e137a9dcd8d8db2e6ebb3917117da621d43e787..538a3b96b699ee00be5dba33f23cdd764b301e99 100644 (file)
--- a/doc/man/lttng-enable-event.1.txt
+++ b/doc/man/lttng-enable-event.1.txt
@@ -410,8 +410,10 @@ Dynamic user space probes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 With the option:--userspace-probe option, you can instrument function
 entries of any user space binary (application or library) using either
-an available symbol name or a SystemTap SDT probe's provider and probe
-names.
+an available symbol name or a SystemTap Statically Defined Tracepoints
+(SDT, a DTrace-style marker) probe's provider and probe names. As of
+this version, only SDT probes that are :not: surrounded by a reference
+counter (semaphore).
 
 The option:--userspace-probe option must be specified with the
 option:--kernel option because it uses Linux's uprobe feature to
@@ -420,12 +422,73 @@ dynamically instrument a user space application or library.
 As of this version, dynamic probe events do not record any payload
 field.
 
-The two available option:--userspace-probe option's argument formats
-are:
 
-option:--userspace-probe=`[elf:]PATH:SYMBOL`::
+include::common-cmd-options-head.txt[]
+
+
+Domain
+~~~~~~
+One of:
+
+option:-j, option:--jul::
+    Create or enable event rules in the `java.util.logging`
+    (JUL) domain.
+
+option:-k, option:--kernel::
+    Create or enable event rules in the Linux kernel domain.
+
+option:-l, option:--log4j::
+    Create or enable event rules in the Apache log4j domain.
+
+option:-p, option:--python::
+    Create or enable event rules in the Python domain.
+
+option:-u, option:--userspace::
+    Create or enable event rules in the user space domain.
+
+
+Target
+~~~~~~
+option:-c 'CHANNEL', option:--channel='CHANNEL'::
+    Create or enable event rules in the channel named 'CHANNEL' instead
+    of the default channel name `channel0`.
+
+option:-s 'SESSION', option:--session='SESSION'::
+    Create or enable event rules in the tracing session named 'SESSION'
+    instead of the current tracing session.
+
+
+Event source type
+~~~~~~~~~~~~~~~~~
+One of:
+
+option:--function='SOURCE'::
+    Dynamic kernel return probe (kretprobe). Only available with the
+    option:--kernel domain option. 'SOURCE' is one of:
++
+* Function address (`0x` prefix supported)
+* Function symbol name
+* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+
+option:--probe='SOURCE'::
+    Dynamic kernel probe (kprobe). Only available with the
+    option:--kernel domain option. 'SOURCE' is one of:
++
+* Address (`0x` prefix supported)
+* Symbol nane
+* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
+
+option:--userspace-probe='SOURCE'::
+    Dynamic user space probe (uprobe). Only available with the
+    option:--kernel domain option. See the
+    <<userspace-probe,Dynamic user space probes>> section.
++
+'SOURCE' is one of:
++
+--
+\[++elf:++]__PATH__++:++__SYMBOL__::
     Dynamically instrument an available symbol within a user space
-    executable.
+    application or library.
 +
 --
 'PATH'::
@@ -435,7 +498,7 @@ This can be:
 +
 * An absolute path.
 * A relative path.
-* An executable's name as found in the directories listed in the
+* An application's name as found in the directories listed in the
   `PATH` environment variable.
 
 'SYMBOL'::
@@ -455,8 +518,9 @@ Examples:
 * `--userspace-probe=./myapp:createUser`
 * `--userspace-probe=httpd:ap_run_open_htaccess`
 
-option:--userspace-probe=`sdt:PATH:PROVIDER:NAME`::
-    Dynamically instrument an SDT probe within a user space executable.
+++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
+    Dynamically instrument an SDT probe within a user space application
+    or library.
 +
 --
 'PATH'::
@@ -466,10 +530,10 @@ This can be:
 +
 * An absolute path.
 * A relative path.
-* An executable's name as found in the directories listed in the
+* An application's name as found in the directories listed in the
   `PATH` environment variable.
 
-__PROVIDER__:__NAME__::
+__PROVIDER__++:++__NAME__::
     SDT provider and probe names.
 +
 For example, with the following SDT probe:
@@ -486,69 +550,7 @@ The provider/probe name pair is `server:accept_request`.
 Example:
 +
 * `--userspace-probe=sdt:./build/server:server:accept_request`
-
-
-include::common-cmd-options-head.txt[]
-
-
-Domain
-~~~~~~
-One of:
-
-option:-j, option:--jul::
-    Create or enable event rules in the `java.util.logging`
-    (JUL) domain.
-
-option:-k, option:--kernel::
-    Create or enable event rules in the Linux kernel domain.
-
-option:-l, option:--log4j::
-    Create or enable event rules in the Apache log4j domain.
-
-option:-p, option:--python::
-    Create or enable event rules in the Python domain.
-
-option:-u, option:--userspace::
-    Create or enable event rules in the user space domain.
-
-
-Target
-~~~~~~
-option:-c 'CHANNEL', option:--channel='CHANNEL'::
-    Create or enable event rules in the channel named 'CHANNEL' instead
-    of the default channel name `channel0`.
-
-option:-s 'SESSION', option:--session='SESSION'::
-    Create or enable event rules in the tracing session named 'SESSION'
-    instead of the current tracing session.
-
-
-Event source type
-~~~~~~~~~~~~~~~~~
-One of:
-
-option:--function='SOURCE'::
-    Linux kernel kretprobe. Only available with the option:--kernel
-    domain option. 'SOURCE' is one of:
-+
-* Function address (`0x` prefix supported)
-* Function symbol
-* Function symbol and offset (`SYMBOL+OFFSET` format)
-
-option:--probe='SOURCE'::
-    Linux kernel kprobe. Only available with the option:--kernel
-    domain option. 'SOURCE' is one of:
-+
-* Address (`0x` prefix supported)
-* Symbol
-* Symbol and offset (`SYMBOL+OFFSET` format)
-
-option:--userspace-probe='SOURCE'::
-    Linux kernel uprobe. Only available with the option:--kernel
-    domain option.
-+
-See the <<userspace-probe,Dynamic user space probes>> section for more
-information about the option's argument 'SOURCE'.
+--
 
 option:--syscall::
     Linux kernel system call. Only available with the option:--kernel