[Libguestfs] [PATCH nbdkit 1/4] fua: Revise and clarify the nbdkit-fua-filter manual page.

[Richard W.M. Jones]

Break up the large paragraph and split up some longer sentences to
make it easier to read.
---
 filters/fua/nbdkit-fua-filter.pod | 51 ++++++++++++++++++++-----------
 1 file changed, 34 insertions(+), 17 deletions(-)

diff --git a/filters/fua/nbdkit-fua-filter.pod b/filters/fua/nbdkit-fua-filter.pod
index 0411f9f4..6e8f87e2 100644
--- a/filters/fua/nbdkit-fua-filter.pod
+++ b/filters/fua/nbdkit-fua-filter.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-nbdkit-fua-filter - nbdkit FUA filter
+nbdkit-fua-filter - modify nbdkit flush and Forced Unit Access (FUA)
 
 =head1 SYNOPSIS
 
@@ -9,47 +9,60 @@ nbdkit-fua-filter - nbdkit FUA filter
 =head1 DESCRIPTION
 
 C<nbdkit-fua-filter> is a filter that intentionally modifies handling
-of the 'Forced Unit Access' (FUA) flag across the NBD protocol.  It is
-mainly useful for testing client or server fallbacks, and for
+of the S<“Forced Unit Access”> (FUA) flag across the NBD protocol.  It
+is mainly useful for testing client or server fallbacks, and for
 evaluating timing differences between proper use of FUA compared to a
 full flush.
 
 =head1 PARAMETERS
 
+The C<fuamode> parameter is optional and controls which mode the
+filter will use.
+
 =over 4
 
 =item B<fuamode=none>
 
+FUA support is not advertised to the client.  This is the default if
+the C<fuamode> parameter is not specified.
+
 =item B<fuamode=emulate>
 
+The filter will emulate FUA support using the plugin’s C<.flush>
+callback, regardless of whether the plugin itself supports more
+efficient FUA.  It refuses to load if the plugin does not support
+flush.
+
 =item B<fuamode=native>
 
+The filter will advertise native FUA support to the client and earlier
+filters in the chain.  This is useful for comparing optimizations of
+FUA handling when splitting large requests into sub-requests.  It
+refuses to load if the plugin’s C<.can_fua> callback returns
+C<NBDKIT_FUA_NONE>.
+
 =item B<fuamode=force>
 
-Optional, controls which mode the filter will use.  Mode B<none>
-(default) means that FUA support is not advertised to the client.
-Mode B<emulate> causes the filter to emulate FUA support using the
-plugin's C<flush> callback, regardless of whether the plugin itself
-supports more efficient FUA (or refuses to load if the plugin's
-C<can_flush> callback returns false).  Mode B<native> causes the
-filter to advertise native FUA support to earlier filters, useful for
-comparing optimizations of FUA handling when splitting large requests
-into sub-requests (or refuses to load if the plugin's C<can_fua>
-callback returns C<NBDKIT_FUA_NONE>).  Mode B<force> causes the filter
-to request FUA on all write transactions, even when the client did not
-request it, and in turn treats client flush requests as a no-op (or
-refuses to load if the plugin's C<can_fua> callback returns
-C<NBDKIT_FUA_NONE>).
+The filter will request FUA on all write transactions, even when the
+client did not request it.  In turn client flush requests become
+no-ops.  It refuses to load if the plugin's C<.can_fua> callback
+returns C<NBDKIT_FUA_NONE>.
 
 =back
 
 =head1 EXAMPLES
 
+=over 4
+
+=item *
+
 Serve the file F<disk.img>, but force the client to submit explicit
 flush requests instead of using C<NBD_CMD_FLAG_FUA>:
 
  nbdkit --filter=fua file disk.img
 
+=item *
+
 Observe that the blocksize filter optimizes its handling of the FUA
 flag based on whether it knows nbdkit will be emulating FUA with a
 flush, by comparing the log filter output on top of different fua
@@ -60,12 +73,16 @@ filter modes:
  nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
    maxlen=4k logfile=fua_native fuamode=native
 
+=item *
+
 Serve the file F<disk.img> in write-through mode, where all writes
 from the client are immediately flushed to disk as if the client had
 always requested FUA:
 
  nbdkit --filter=fua file fuamode=force disk.img
 
+=back
+
 =head1 FILES
 
 =over 4
-- 
2.25.0