From 166be40fa335649caf2615b384cc006d92bc5170 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Sun, 15 Jul 2018 11:14:49 +0100
Subject: [PATCH 03/12] streaming: Add illustrations to the man page.

Also improve the flow of the language and provide cross-reference to
captive nbdkit.
---
 plugins/streaming/nbdkit-streaming-plugin.pod | 25 ++++++++++++++++---
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/plugins/streaming/nbdkit-streaming-plugin.pod b/plugins/streaming/nbdkit-streaming-plugin.pod
index a4a9714..98e8337 100644
--- a/plugins/streaming/nbdkit-streaming-plugin.pod
+++ b/plugins/streaming/nbdkit-streaming-plugin.pod
@@ -18,16 +18,33 @@ end of the disk without seeking backwards, then this plugin will turn
 the resulting disk image into a stream of data which is written to the
 named C<pipe> parameter.
 
-Typical usage is with qemu tools.  For example:
+               ┌───────────┐
+ client        │ nbdkit    │        plugin streams
+ writes ──────▶│ streaming │──────▶ data to pipe
+               │ plugin    │
+               └───────────┘
 
- qemu-img convert input -O raw output
+Typical usage is with qemu tools.  The following command will I<not>
+work because the output is a pipe or socket:
 
-does I<not> work if C<output> is a pipe.  However this does:
+ qemu-img convert input -O raw pipe
 
- nbdkit -U /tmp/nbd.sock streaming pipe=output --run '
+However this will work:
+
+ nbdkit -U - streaming pipe=pipe --run '
    qemu-img convert -n input -O raw $nbd
  '
 
+              ┌───────────┐       ┌───────────┐
+ reads        │ qemu-img  │       │ nbdkit    │        plugin streams
+ input ──────▶│ convert   │──────▶│ streaming │──────▶ data to pipe
+ file         │ command   │       │ plugin    │
+              └───────────┘      ↑└───────────┘
+                              Unix domain socket (-U -)
+
+For use of the I<--run> and I<-U -> options, see
+L<nbdkit(1)/CAPTIVE NBDKIT>.
+
 =head1 PARAMETERS
 
 =over 4
-- 
2.17.1