doc/man: use double quotes when referring to internal section

[deliverable/lttng-tools.git] / doc / man / lttng-snapshot.1.txt

diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt
index 27c1e3d9c41821a9f97068bc3ac368da68b8160d..7886bbde54bc258d2a67fc2883ad878ce04e7f24 100644 (file)
--- a/doc/man/lttng-snapshot.1.txt
+++ b/doc/man/lttng-snapshot.1.txt
@@ -1,6 +1,6 @@
 lttng-snapshot(1)
 =================
-:revdate: 3 May 2021
+:revdate: 17 May 2021
 
 
 NAME
@@ -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
-<<output,Snapshot output>> section below to learn more.
+``<<output,Snapshot output>>'' 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,6 +69,8 @@ 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 ``<<examples,EXAMPLES>>'' 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,
 see the tracing session rotation feature in man:lttng-concepts(7). Trace
@@ -145,7 +147,7 @@ Set the maximum total size of all the snapshot trace files LTTng writes
 with the option:--max-size option.
 
 
-include::common-cmd-options-head.txt[]
+include::common-lttng-cmd-options-head.txt[]
 
 
 Recording target
@@ -157,7 +159,7 @@ option:-s 'SESSION', option:--session='SESSION'::
 
 Output
 ~~~~~~
-See the <<output,Snapshot output>> section above.
+See the ``<<output,Snapshot output>>'' section above.
 
 option:-C 'URL', option:--ctrl-url='URL'::
     Set the control path URL to 'URL'.
@@ -184,10 +186,69 @@ option:-n 'NAME', option:--name='NAME'::
     Assign the name 'NAME' to the snapshot output.
 
 
-include::common-cmd-help-options.txt[]
+include::common-lttng-cmd-help-options.txt[]
+
+
+include::common-lttng-cmd-after-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Take a snapshot of the current tracing session, sending the trace files to its snapshot output.
+====
+[role="term"]
+----
+$ lttng snapshot record
+----
+====
+
+.Take a snapshot of a specific tracing session, giving it a custom name.
+====
+See the option:--session and option:--name options.
+
+[role="term"]
+----
+$ lttng snapshot record --session=my-session --name=SNAP
+----
+====
+
+.Take a snapshot of the current tracing session, sending the trace files to a custom location.
+====
+See the ``Output directory'' section of man:lttng-relayd(8) to
+understand where the relay daemon to connect to (`3.96.87.215`) writes
+the received traces.
+
+[role="term"]
+----
+$ lttng snapshot record net://3.96.87.215
+----
+====
+
+.Replace the snapshot output of a specific tracing session with a local file system path.
+====
+See the option:--session option.
+
+[role="term"]
+----
+$ lttng snapshot del-output --session=monk 1
+$ lttng snapshot add-output --session=monk \
+                 file:///path/to/snapshots
+----
+====
+
+.Take a snapshot of the current tracing session, making sure its size is not over 4{nbsp}MiB.
+====
+See the option:--max-size option.
+
+[role="term"]
+----
+$ lttng snapshot record --max-size=4M
+----
+====
 
 
-include::common-cmd-footer.txt[]
+include::common-footer.txt[]
 
 
 SEE ALSO