thr3ads.net - Libguestfs - [Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs [May 2022]

If this information is useful, please help other people find it:
Share via:

Richard W.M. Jones

2022-May-21 14:09 UTC

[Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs

POD verbatim paragraphs are introduced by a line starting with
whitespace and continue to the next line containing only whitespace
(or empty).  In the output they appear as preformatted text (like
<pre/> in HTML).  We use them extensively, but also as it turns out,
wrongly.

I previously assumed that all lines of the verbatim paragraph had to
be indented, but this is not true.  More seriously, adjacent verbatim
paragraphs are always run together, whether or not there is a line
containing whitespace between the paragraphs or not.  As an example,
these three pieces of POD would be formatted identically (I have used
?|? to mark the beginning and end of each line to make whitespace
clear):

        (1)                  (2)                  (3)
  | nbdkit foo \|      | nbdkit foo \|      | nbdkit foo \|
  | --dump-plugin|     |--dump-plugin|      | --dump-plugin|
  | |                  | |                  ||
  | nbdkit bar|        | nbdkit bar|        | nbdkit bar|

In all cases, there are two verbatim paragraphs, the first paragraph
has two lines and the second has one line.  The output is 4 lines of
preformatted text, grouped together.  In HTML output that would mean a
single <pre/> element.

In previous usage, we assumed that a space on a line on its own would
cause the adjacent verbatim paragraphs to be grouped together, but a
completely blank line would cause the two verbatim paragraphs to be
split.  As you can see in case (3) above, this does not work.

It is in fact possible to have adjacent verbatim paragraphs not be
grouped together.  It involves inserting an empty, zero length
ordinary paragraph between the two, which can be done using the
?=for paragraph? syntax:

 nbdkit foo \
 --dump-plugin

 =for paragraph

 nbdkit bar

In HTML output this will be formatted as two <pre/> elements.  Note
that the blank lines before and after ?=for paragraph? are necessary.

This commit reformats all existing POD documentation in nbdkit to
conform.  There are two main changes:

(a) Lines which contain only whitespace (ie. those we previously used
to mean ?group these verbatim paragraphs together?) are replaced with
completely empty lines.

(b) Completely empty lines occurring between two verbatim paragraphs
are replaced with ?\n=for paragraph\n\n?, ie. inserting a blank
ordinary paragraph to stop the verbatim paragraphs from running
together.

The following commit adds syntax checking to podwrapper to identify
trailing whitespace in POD files, so that we don't introduce this kind
of error in future.

Note that I don't try to unindent the verbatim paragraphs, because
that looks weird and also makes it harder for us to parse the POD in
case we needed to in future.

This commit change was made mechanically using this Perl script:

use strict;

foreach my $input (@ARGV) {
    my $content;
    { local $/ = undef;
      open FILE, "<:encoding(UTF-8)", $input or die "$input:
$!";
      $content = <FILE> }
    # Verbatim paragraphs separated by empty line, means do not group.
    $content =~ s/(\n [^\n]*)\n\n /$1\n\n=for paragraph\n\n /g;
    # Any remaining lines containing only whitespace, group.
    $content =~ s/\n[ \t]+\n/\n\n/g;
    rename ($input, "$input.bak");
    open FILE, ">:encoding(UTF-8)", $input or die "$input:
$!";
    print FILE $content;
}

Thanks: Laszlo Ersek
See-also:
https://listman.redhat.com/archives/libguestfs/2022-May/thread.html#28902
---
 docs/nbdkit-captive.pod                        |  2 ++
 docs/nbdkit-filter.pod                         | 14 +++++++++-----
 docs/nbdkit-plugin.pod                         | 12 +++++++-----
 docs/nbdkit-probing.pod                        |  4 ++++
 docs/nbdkit-service.pod                        |  4 ++--
 docs/nbdkit.pod                                |  2 ++
 .../checkwrite/nbdkit-checkwrite-filter.pod    |  2 ++
 filters/ddrescue/nbdkit-ddrescue-filter.pod    |  2 ++
 filters/delay/nbdkit-delay-filter.pod          |  2 ++
 filters/ext2/nbdkit-ext2-filter.pod            |  2 ++
 filters/readahead/nbdkit-readahead-filter.pod  |  2 ++
 filters/scan/nbdkit-scan-filter.pod            |  2 ++
 filters/stats/nbdkit-stats-filter.pod          |  8 ++++----
 filters/swab/nbdkit-swab-filter.pod            |  4 ++++
 filters/xz/nbdkit-xz-filter.pod                |  2 ++
 plugins/S3/nbdkit-S3-plugin.pod                |  2 +-
 plugins/cc/nbdkit-cc-plugin.pod                | 18 +++++++++---------
 plugins/curl/nbdkit-curl-plugin.pod            |  4 ++--
 plugins/data/nbdkit-data-plugin.pod            |  8 ++++++++
 plugins/file/nbdkit-file-plugin.pod            |  2 ++
 plugins/golang/nbdkit-golang-plugin.pod        |  8 ++++----
 plugins/guestfs/nbdkit-guestfs-plugin.pod      |  4 ++++
 plugins/info/nbdkit-info-plugin.pod            |  2 ++
 plugins/memory/nbdkit-memory-plugin.pod        |  4 ++--
 plugins/nbd/nbdkit-nbd-plugin.pod              |  4 ++++
 plugins/ocaml/nbdkit-ocaml-plugin.pod          |  6 ++++--
 plugins/ondemand/nbdkit-ondemand-plugin.pod    |  2 ++
 plugins/rust/nbdkit-rust-plugin.pod            |  6 ++++--
 plugins/sh/nbdkit-sh-plugin.pod                |  4 ++++
 plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod      |  2 ++
 30 files changed, 102 insertions(+), 38 deletions(-)

diff --git a/docs/nbdkit-captive.pod b/docs/nbdkit-captive.pod
index d41a824d..8fee3913 100644
--- a/docs/nbdkit-captive.pod
+++ b/docs/nbdkit-captive.pod
@@ -7,6 +7,8 @@ reliably cleaned up
 
  nbdkit PLUGIN [...] [-e|--exportname EXPORTNAME] --run "CMD ARGS
..."
 
+=for paragraph
+
  nbdkit --exit-with-parent PLUGIN [...]
 
 =head1 DESCRIPTION
diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod
index 587b012e..1bf6468a 100644
--- a/docs/nbdkit-filter.pod
+++ b/docs/nbdkit-filter.pod
@@ -5,7 +5,7 @@ nbdkit-filter - how to write nbdkit filters
 =head1 SYNOPSIS
 
  #include <nbdkit-filter.h>
- 
+
  static int
  myfilter_config (nbdkit_next_config *next, void *nxdata,
                   const char *key, const char *value)
@@ -19,13 +19,13 @@ nbdkit-filter - how to write nbdkit filters
      return next (nxdata, key, value);
    }
  }
- 
+
  static struct nbdkit_filter filter = {
    .name              = "filter",
    .config            = myfilter_config,
    /* etc */
  };
- 
+
  NBDKIT_REGISTER_FILTER(filter)
 
 When this has been compiled to a shared library, do:
@@ -72,7 +72,7 @@ parameters the filter can intercept the C<.config>
method:
      return next (nxdata, key, value);
    }
  }
- 
+
  static struct nbdkit_filter filter = {
    // ...
    .config            = myfilter_config,
@@ -118,7 +118,7 @@ that the filter wants to intercept.
    .config            = myfilter_config,
    /* etc */
  };
- 
+
  NBDKIT_REGISTER_FILTER(filter)
 
 The C<.name> field is the name of the filter.  This is the only field
@@ -501,6 +501,8 @@ from the layer below.  Without error checking it would look
like this:
    struct nbdkit_export e;
    char *name, *desc;
 
+=for paragraph
+
    exports2 = nbdkit_exports_new ();
    next_list_exports (nxdata, readonly, exports);
    for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
@@ -948,6 +950,8 @@ from the layer below.  Without error checking it would look
like this:
    struct nbdkit_extent e;
    int64_t size;
 
+=for paragraph
+
    size = next->get_size (next);
    extents2 = nbdkit_extents_new (offset + shift, size);
    next->extents (next, count, offset + shift, flags, extents2, err);
diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod
index bcea900f..383dcffe 100644
--- a/docs/nbdkit-plugin.pod
+++ b/docs/nbdkit-plugin.pod
@@ -6,16 +6,16 @@ nbdkit-plugin - how to write nbdkit plugins
 
  #define NBDKIT_API_VERSION 2
  #include <nbdkit-plugin.h>
- 
+
  #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
- 
+
  static void *
  myplugin_open (void)
  {
    /* create a handle ... */
    return handle;
  }
- 
+
  static struct nbdkit_plugin plugin = {
    .name              = "myplugin",
    .open              = myplugin_open,
@@ -172,7 +172,7 @@ the plugin:
  ??????????????           ? close      ?
  ? close      ?           ??????????????
  ??????????????
- 
+
                    ?           before nbdkit exits
                    ?
          ????????????????????
@@ -1471,7 +1471,7 @@ passwords from config parameters:
 For example:
 
  char *password = NULL;
- 
+
  static int
  myplugin_config (const char *key, const char *value)
  {
@@ -1946,6 +1946,8 @@ written in Perl called C<foo.pl> might be installed
like this:
  $ head -1 foo.pl
  #!/usr/sbin/nbdkit perl
 
+=for paragraph
+
  $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
 
 and then users will be able to run it like this:
diff --git a/docs/nbdkit-probing.pod b/docs/nbdkit-probing.pod
index 55e6d193..05be8fbd 100644
--- a/docs/nbdkit-probing.pod
+++ b/docs/nbdkit-probing.pod
@@ -6,10 +6,14 @@ nbdkit-probing - how to probe for nbdkit configuration and
plugins
 
  nbdkit --dump-config
 
+=for paragraph
+
  nbdkit PLUGIN --dump-plugin
 
  nbdkit --version
 
+=for paragraph
+
  nbdkit PLUGIN --version
 
  nbdkit --filter=FILTER null --version
diff --git a/docs/nbdkit-service.pod b/docs/nbdkit-service.pod
index 03b6ea2d..e3eef6ba 100644
--- a/docs/nbdkit-service.pod
+++ b/docs/nbdkit-service.pod
@@ -31,10 +31,10 @@ containing:
 
  [Unit]
  Description=NBDKit Network Block Device server
- 
+
  [Socket]
  ListenStream=10809
- 
+
  [Install]
  WantedBy=sockets.target
 
diff --git a/docs/nbdkit.pod b/docs/nbdkit.pod
index ef3869f7..c5ea9a35 100644
--- a/docs/nbdkit.pod
+++ b/docs/nbdkit.pod
@@ -74,6 +74,8 @@ L<nbdkit-curl-plugin(1)> or
L<nbdkit-ssh-plugin(1)>:
 
  nbdkit -r curl https://example.com/disk.img
 
+=for paragraph
+
  nbdkit ssh host=example.com /var/tmp/disk.img
 
 =item *
diff --git a/filters/checkwrite/nbdkit-checkwrite-filter.pod
b/filters/checkwrite/nbdkit-checkwrite-filter.pod
index 60f8afa8..04d8c6c5 100644
--- a/filters/checkwrite/nbdkit-checkwrite-filter.pod
+++ b/filters/checkwrite/nbdkit-checkwrite-filter.pod
@@ -31,6 +31,8 @@ filter, and copying from and to nbdkit at the same time:
  nbdkit -U - --filter=checkwrite data "@32768 1" \
         --run 'nbdcopy "$uri" "$uri"'
 
+=for paragraph
+
  nbdkit -U - --filter=checkwrite file disk.img \
         --run 'nbdcopy "$uri" "$uri"'
 
diff --git a/filters/ddrescue/nbdkit-ddrescue-filter.pod
b/filters/ddrescue/nbdkit-ddrescue-filter.pod
index 601d58fa..eadd392d 100644
--- a/filters/ddrescue/nbdkit-ddrescue-filter.pod
+++ b/filters/ddrescue/nbdkit-ddrescue-filter.pod
@@ -7,6 +7,8 @@ nbdkit-ddrescue-filter - nbdkit filter for serving from ddrescue
dump
  nbdkit --filter=ddrescue plugin [plugin-args...]
                                  ddrescue-mapfile=file.map
 
+=for paragraph
+
  nbdkit --filter=ddrescue file file=file.img ddrescue-mapfile=file.map
                                [plugin-args...]
 
diff --git a/filters/delay/nbdkit-delay-filter.pod
b/filters/delay/nbdkit-delay-filter.pod
index 76614736..65c00584 100644
--- a/filters/delay/nbdkit-delay-filter.pod
+++ b/filters/delay/nbdkit-delay-filter.pod
@@ -6,6 +6,8 @@ nbdkit-delay-filter - nbdkit delay filter
 
  nbdkit --filter=delay plugin rdelay=SECS wdelay=SECS [plugin-args...]
 
+=for paragraph
+
  nbdkit --filter=delay plugin rdelay=NNms wdelay=NNms [plugin-args...]
 
  nbdkit --filter=delay plugin [plugin-args ...]
diff --git a/filters/ext2/nbdkit-ext2-filter.pod
b/filters/ext2/nbdkit-ext2-filter.pod
index c15a2fcb..b2064e8a 100644
--- a/filters/ext2/nbdkit-ext2-filter.pod
+++ b/filters/ext2/nbdkit-ext2-filter.pod
@@ -7,6 +7,8 @@ ext4 filesystems
 
  nbdkit --filter=ext2 file fs.img ext2file=/disks/disk.raw
 
+=for paragraph
+
  nbdkit --filter=ext2 --filter=partition file fs.img \
     partition=1 ext2file=exportname
 
diff --git a/filters/readahead/nbdkit-readahead-filter.pod
b/filters/readahead/nbdkit-readahead-filter.pod
index 99d64dfb..29d330ac 100644
--- a/filters/readahead/nbdkit-readahead-filter.pod
+++ b/filters/readahead/nbdkit-readahead-filter.pod
@@ -6,6 +6,8 @@ nbdkit-readahead-filter - prefetch data ahead of sequential
reads
 
  nbdkit --filter=readahead PLUGIN
 
+=for paragraph
+
  nbdkit --filter=readahead --filter=cache PLUGIN
 
  nbdkit --filter=readahead --filter=cow PLUGIN cow-on-cache=true
diff --git a/filters/scan/nbdkit-scan-filter.pod
b/filters/scan/nbdkit-scan-filter.pod
index 2fe9bb80..5a096a78 100644
--- a/filters/scan/nbdkit-scan-filter.pod
+++ b/filters/scan/nbdkit-scan-filter.pod
@@ -7,6 +7,8 @@ nbdkit-scan-filter - scan disk prefetching data ahead of
sequential reads
  nbdkit --filter=scan PLUGIN [scan-ahead=false] [scan-clock=false]
                              [scan-forever=true] [scan-size=]NN
 
+=for paragraph
+
  nbdkit --filter=scan --filter=cache PLUGIN
 
  nbdkit --filter=scan --filter=cow PLUGIN cow-on-cache=true
diff --git a/filters/stats/nbdkit-stats-filter.pod
b/filters/stats/nbdkit-stats-filter.pod
index 0e89f237..9bf25723 100644
--- a/filters/stats/nbdkit-stats-filter.pod
+++ b/filters/stats/nbdkit-stats-filter.pod
@@ -25,7 +25,7 @@ are written to a file once when nbdkit exits.
  write: 1088 ops, 0.065065 s, 132.38 MiB, 1.99 GiB/s op, 38.98 MiB/s total
  trim: 14 ops, 0.002037 s, 25.00 GiB, 12272.95 GiB/s op, 7.36 GiB/s total
  flush: 5 ops, 0.000002 s, 0 bytes, 0 bytes/s op, 0 bytes/s total
- 
+
  READ request sizes:
       4096 bytes: 66.2% of requests (96)
           12 bit aligned: 100.0% (96)
@@ -41,19 +41,19 @@ are written to a file once when nbdkit exits.
           17 bit aligned:  71.4% (5)
           19 bit aligned:  42.9% (3)
      other sizes: 29.0% of requests (42)
- 
+
  WRITE request sizes:
     131072 bytes: 97.1% of requests (1056)
           17 bit aligned: 100.0% (1056)
           18 bit aligned:  50.0% (528)
           19+ bit-aligned: 25.0% (264)
      other sizes:  2.9% of requests (32)
- 
+
  TRIM request sizes:
  2147483648 bytes: 85.7% of requests (12)
           24 bit aligned: 100.0% (12)
      other sizes: 14.3% of requests (2)
- 
+
  ZERO request sizes:
      (no such requests)
 
diff --git a/filters/swab/nbdkit-swab-filter.pod
b/filters/swab/nbdkit-swab-filter.pod
index 6e036270..e7c15ba7 100644
--- a/filters/swab/nbdkit-swab-filter.pod
+++ b/filters/swab/nbdkit-swab-filter.pod
@@ -58,6 +58,8 @@ This swaps the endianness of each 4 byte word in the disk, ie:
 
   input    0   1   2   3   4   5   6   7
 
+=for paragraph
+
  output    3   2   1   0   7   6   5   4
 
 =item B<swab-bits=64>
@@ -66,6 +68,8 @@ This swaps the endianness of each 8 byte word in the disk, ie:
 
   input    0   1   2   3   4   5   6   7
 
+=for paragraph
+
  output    7   6   5   4   3   2   1   0
 
 This can be used to make L<nbdkit-pattern-plugin(1)> little endian
diff --git a/filters/xz/nbdkit-xz-filter.pod b/filters/xz/nbdkit-xz-filter.pod
index 88cd569f..8248efb5 100644
--- a/filters/xz/nbdkit-xz-filter.pod
+++ b/filters/xz/nbdkit-xz-filter.pod
@@ -6,6 +6,8 @@ nbdkit-xz-filter - nbdkit xz filter
 
  nbdkit --filter=xz file FILENAME.xz
 
+=for paragraph
+
  nbdkit --filter=xz curl https://example.com/FILENAME.xz
 
 =head1 DESCRIPTION
diff --git a/plugins/S3/nbdkit-S3-plugin.pod b/plugins/S3/nbdkit-S3-plugin.pod
index bd978fc1..52188535 100644
--- a/plugins/S3/nbdkit-S3-plugin.pod
+++ b/plugins/S3/nbdkit-S3-plugin.pod
@@ -107,7 +107,7 @@ F<~/.aws/credentials> file.  This takes the form:
  [default]
  aws_access_key_id = XXX
  aws_secret_access_key = YYY
- 
+
  [profile]
  aws_access_key_id = XXX
  aws_secret_access_key = YYY
diff --git a/plugins/cc/nbdkit-cc-plugin.pod b/plugins/cc/nbdkit-cc-plugin.pod
index be4019f9..b7099beb 100644
--- a/plugins/cc/nbdkit-cc-plugin.pod
+++ b/plugins/cc/nbdkit-cc-plugin.pod
@@ -136,26 +136,26 @@ All other parameters on the command line are passed to the
plugin.
  $ nbdkit cc - <<'EOF'
  #include <stdint.h>
  #include <string.h>
- 
+
  #define NBDKIT_API_VERSION 2
  #include <nbdkit-plugin.h>
- 
+
  char data[10*1024*1024];
- 
+
  #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
- 
+
  static void *
  my_open (int readonly)
  {
    return NBDKIT_HANDLE_NOT_NEEDED;
  }
- 
+
  static int64_t
  my_get_size (void *handle)
  {
    return (int64_t) sizeof (data);
  }
- 
+
  static int
  my_pread (void *handle, void *buf,
            uint32_t count, uint64_t offset,
@@ -164,7 +164,7 @@ All other parameters on the command line are passed to the
plugin.
    memcpy (buf, data+offset, count);
    return 0;
  }
- 
+
  static int
  my_pwrite (void *handle, const void *buf,
             uint32_t count, uint64_t offset,
@@ -173,7 +173,7 @@ All other parameters on the command line are passed to the
plugin.
    memcpy (data+offset, buf, count);
    return 0;
  }
- 
+
  static struct nbdkit_plugin plugin = {
    .name              = "myplugin",
    .open              = my_open,
@@ -181,7 +181,7 @@ All other parameters on the command line are passed to the
plugin.
    .pread             = my_pread,
    .pwrite            = my_pwrite,
  };
- 
+
  NBDKIT_REGISTER_PLUGIN(plugin)
  EOF
 
diff --git a/plugins/curl/nbdkit-curl-plugin.pod
b/plugins/curl/nbdkit-curl-plugin.pod
index fc422ca2..e422aca7 100644
--- a/plugins/curl/nbdkit-curl-plugin.pod
+++ b/plugins/curl/nbdkit-curl-plugin.pod
@@ -403,7 +403,7 @@ I<--insecure> and C<sslverify=false>.
  DS=datastore1
  GUEST=guest-name
 
URL="https://$SERVER/folder/$GUEST/$GUEST-flat.vmdk?dcPath=$DCPATH&dsName=$DS"
- 
+
  nbdkit curl "$URL" \
         cookie-script='
             curl --head -s --insecure -u root:password "$url" |
@@ -442,7 +442,7 @@ check they are working.  To run nbdkit:
  IMAGE=library/fedora
  BLOBSUM=`/tmp/blobsum.sh`
  URL="https://registry-1.docker.io/v2/$IMAGE/blobs/$BLOBSUM"
- 
+
  nbdkit curl "$URL" \
         header-script=' printf "Authorization: Bearer ";
/tmp/auth.sh ' \
         header-script-renew=200 \
diff --git a/plugins/data/nbdkit-data-plugin.pod
b/plugins/data/nbdkit-data-plugin.pod
index 6e52394a..32f52fde 100644
--- a/plugins/data/nbdkit-data-plugin.pod
+++ b/plugins/data/nbdkit-data-plugin.pod
@@ -7,9 +7,13 @@ nbdkit-data-plugin - nbdkit plugin for serving data from the
command line
  nbdkit data [data=]'0 1 2 3 @0x1fe 0x55 0xaa'
              [size=SIZE] [allocator=sparse|malloc|zstd]
 
+=for paragraph
+
  nbdkit data base64='aGVsbG8gbmJka2l0IHVzZXI='
              [size=SIZE] [allocator=sparse|malloc|zstd]
 
+=for paragraph
+
  nbdkit data raw='binary_data'
              [size=SIZE] [allocator=sparse|malloc|zstd]
 
@@ -351,9 +355,13 @@ expressions.  These are all equivalent:
 
  nbdkit data '$pattern*16' pattern='0x55 0xAA'
 
+=for paragraph
+
  export pattern='0x55 0xAA'
  nbdkit data '$pattern*16'
 
+=for paragraph
+
  nbdkit data '( 0x55 0xAA )*16'
 
 =item B<#> COMMENT
diff --git a/plugins/file/nbdkit-file-plugin.pod
b/plugins/file/nbdkit-file-plugin.pod
index b95e7349..49c33066 100644
--- a/plugins/file/nbdkit-file-plugin.pod
+++ b/plugins/file/nbdkit-file-plugin.pod
@@ -7,6 +7,8 @@ nbdkit-file-plugin - nbdkit file plugin
  nbdkit file [file=]FILENAME
              [cache=default|none] [fadvise=normal|random|sequential]
 
+=for paragraph
+
  nbdkit file dir=DIRECTORY
 
 =head1 DESCRIPTION
diff --git a/plugins/golang/nbdkit-golang-plugin.pod
b/plugins/golang/nbdkit-golang-plugin.pod
index eb1e6251..34f9a6eb 100644
--- a/plugins/golang/nbdkit-golang-plugin.pod
+++ b/plugins/golang/nbdkit-golang-plugin.pod
@@ -50,7 +50,7 @@ C<nbdkit.Connection> structs respectively:
  type MyPlugin struct {
          nbdkit.Plugin
  }
- 
+
  type MyConnection struct {
          nbdkit.Connection
  }
@@ -65,12 +65,12 @@ should return a new instance of your connection struct.  For
example:
  func (p *MyPlugin) Load() {
          // global callback used for initializing the plugin
  }
- 
+
  func (p *MyPlugin) Open(readonly bool) (nbdkit.ConnectionInterface, error) {
          // new client has connected
          return &MyConnection{}, nil
  }
- 
+
  func (c *MyConnection) GetSize() (uint64, error) {
          // called per-client
          return virtual_size, nil
@@ -109,7 +109,7 @@ C<Zero> (C<CanZero>).
  func (c *MyConnection) CanWrite() (bool, error) {
          return true, nil
  }
- 
+
  func (c *MyConnection) PWrite(buf []byte, offset uint64,
         flags uint32) error {
          // ...
diff --git a/plugins/guestfs/nbdkit-guestfs-plugin.pod
b/plugins/guestfs/nbdkit-guestfs-plugin.pod
index b3d9a872..fc1c6025 100644
--- a/plugins/guestfs/nbdkit-guestfs-plugin.pod
+++ b/plugins/guestfs/nbdkit-guestfs-plugin.pod
@@ -138,6 +138,8 @@ needed.
 
  nbdkit guestfs disk=disk.img export=/dev/sda1
 
+=for paragraph
+
  nbdkit guestfs disk=disk.img export=/dev/VG/LV
 
 Use L<virt-filesystems(1)> to find out what devices, partitions, LVs,
@@ -152,6 +154,8 @@ needed.
 
  nbdkit -r guestfs domain=Guest export=/dev/sda1
 
+=for paragraph
+
  nbdkit -r guestfs domain=Guest export=/dev/VG/LV
 
 =head2 Exporting a file inside a disk image
diff --git a/plugins/info/nbdkit-info-plugin.pod
b/plugins/info/nbdkit-info-plugin.pod
index 8ed9db9a..4bc4aaef 100644
--- a/plugins/info/nbdkit-info-plugin.pod
+++ b/plugins/info/nbdkit-info-plugin.pod
@@ -43,6 +43,8 @@ characters is created.  We then display the contents:
  print("buf = %r" % buf)
  EOF
 
+=for paragraph
+
  size = 5
  buf = b"hello"
 
diff --git a/plugins/memory/nbdkit-memory-plugin.pod
b/plugins/memory/nbdkit-memory-plugin.pod
index 8f0c223f..9e546c3d 100644
--- a/plugins/memory/nbdkit-memory-plugin.pod
+++ b/plugins/memory/nbdkit-memory-plugin.pod
@@ -85,11 +85,11 @@ the memory plugin, use L<qemu-img(1)> or
L<nbdcopy(1)>:
 
  $ rm -f pid
  $ nbdkit -P pid memory 10G
- 
+
 Wait for nbdkit to become ready to accept connections:
 
  $ while [ ! -f pid ]; do sleep 1; done
- 
+
 Preload Fedora disk image using qemu-img:
 
  $ virt-builder fedora-28 --size=10G
diff --git a/plugins/nbd/nbdkit-nbd-plugin.pod
b/plugins/nbd/nbdkit-nbd-plugin.pod
index 484304ee..e907a10b 100644
--- a/plugins/nbd/nbdkit-nbd-plugin.pod
+++ b/plugins/nbd/nbdkit-nbd-plugin.pod
@@ -260,6 +260,8 @@ that the old server exits.
    nbdkit --exit-with-parent --tls=require nbd socket=$sock &
    exec /path/to/oldserver --socket=$sock )
 
+=for paragraph
+
  ??????????????   TLS    ??????????  plaintext  ??????????????
  ? new client ? ?????????? nbdkit ? ????????????? old server ?
  ??????????????   TCP    ??????????    Unix     ??????????????
@@ -298,6 +300,8 @@ limited to a Unix socket on the local machine.
  nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
   --run '/path/to/oldclient --socket=$unixsocket'
 
+=for paragraph
+
  ??????????????  plaintext  ??????????   TLS    ??????????????
  ? old client ? ????????????? nbdkit ? ?????????? new server ?
  ??????????????    Unix     ??????????   TCP    ??????????????
diff --git a/plugins/ocaml/nbdkit-ocaml-plugin.pod
b/plugins/ocaml/nbdkit-ocaml-plugin.pod
index 22048633..38e605d9 100644
--- a/plugins/ocaml/nbdkit-ocaml-plugin.pod
+++ b/plugins/ocaml/nbdkit-ocaml-plugin.pod
@@ -6,6 +6,8 @@ nbdkit-ocaml-plugin - writing nbdkit plugins in OCaml
 
  nbdkit /path/to/plugin.so [arguments...]
 
+=for paragraph
+
  nbdkit plugin [arguments...]
 
 =head1 DESCRIPTION
@@ -77,13 +79,13 @@ handle struct in your plugin:
    h_id : int; (* this is just an example field *)
    h_readonly : bool;
  }
- 
+
  let id = ref 0
  let myplugin_open readonly     (* return a newly allocated handle *)
    incr id;
    { h_id = !id; h_readonly = readonly }
- 
+
  let myplugin_get_size handle     printf "handle ID = %d\n"
handle.h_id;
    (* ... *)
diff --git a/plugins/ondemand/nbdkit-ondemand-plugin.pod
b/plugins/ondemand/nbdkit-ondemand-plugin.pod
index cccaa1d9..a2a14ac1 100644
--- a/plugins/ondemand/nbdkit-ondemand-plugin.pod
+++ b/plugins/ondemand/nbdkit-ondemand-plugin.pod
@@ -96,6 +96,8 @@ commands such as these (note the different export names):
  nbd-client server /dev/nbd0 -N export1
  mount /dev/nbd0 /mnt
 
+=for paragraph
+
  guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda
 
  qemu-img info nbd:localhost:10809:exportname=export2
diff --git a/plugins/rust/nbdkit-rust-plugin.pod
b/plugins/rust/nbdkit-rust-plugin.pod
index 9e3ef10e..114e6947 100644
--- a/plugins/rust/nbdkit-rust-plugin.pod
+++ b/plugins/rust/nbdkit-rust-plugin.pod
@@ -28,16 +28,18 @@ Your Rust code should define a public implementation of the
C<Server> trait,
 and register it using the C<plugin!> macro.
 
  use nbdkit::*;
- 
+
  #[derive(Default)]
  struct MyPlugin {
      // ...
  }
- 
+
  impl Server for MyPlugin {
      // ...
  }
 
+=for paragraph
+
  plugin!(MyPlugin {write_at, trim, ...});
 
 =head2 Compiling a Rust nbdkit plugin
diff --git a/plugins/sh/nbdkit-sh-plugin.pod b/plugins/sh/nbdkit-sh-plugin.pod
index aede1c65..2a55fdc9 100644
--- a/plugins/sh/nbdkit-sh-plugin.pod
+++ b/plugins/sh/nbdkit-sh-plugin.pod
@@ -6,6 +6,8 @@ nbdkit-sh-plugin - nbdkit shell, script or executable plugin
 
  nbdkit sh /path/to/script [arguments...]
 
+=for paragraph
+
  nbdkit sh - <<'EOF'
  ... shell script ...
  EOF
@@ -73,6 +75,8 @@ parameter is always the method name.  For example:
                    ?      ??? key ($2)
                method ($1)
 
+=for paragraph
+
  /path/to/script pread <handle> <count> <offset>
                    ?       ?       ?       ?
                    ?       ?       ?       ?? offset in bytes ($4)
diff --git a/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
b/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
index 9cecad34..b098f2ab 100644
--- a/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
+++ b/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
@@ -6,6 +6,8 @@ nbdkit-tmpdisk-plugin - create a fresh temporary filesystem for
each client
 
  nbdkit tmpdisk [size=]SIZE [type=ext4|xfs|vfat|...] [label=LABEL]
 
+=for paragraph
+
  nbdkit tmpdisk [size=]SIZE command=COMMAND [VAR=VALUE ...]
 
 =head1 DESCRIPTION
-- 
2.35.1

Laszlo Ersek

2022-May-24 13:20 UTC

head link

[Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs

On 05/21/22 16:09, Richard W.M. Jones wrote:> POD verbatim paragraphs are introduced by a line starting with
> whitespace and continue to the next line containing only whitespace
> (or empty).  In the output they appear as preformatted text (like
> <pre/> in HTML).  We use them extensively, but also as it turns out,
> wrongly.
> 
> I previously assumed that all lines of the verbatim paragraph had to
> be indented, but this is not true.  More seriously, adjacent verbatim
> paragraphs are always run together, whether or not there is a line
> containing whitespace between the paragraphs or not.  As an example,
> these three pieces of POD would be formatted identically (I have used
> ?|? to mark the beginning and end of each line to make whitespace
> clear):
> 
>         (1)                  (2)                  (3)
>   | nbdkit foo \|      | nbdkit foo \|      | nbdkit foo \|
>   | --dump-plugin|     |--dump-plugin|      | --dump-plugin|
>   | |                  | |                  ||
>   | nbdkit bar|        | nbdkit bar|        | nbdkit bar|
> 
> In all cases, there are two verbatim paragraphs, the first paragraph
> has two lines and the second has one line.  The output is 4 lines of
> preformatted text, grouped together.  In HTML output that would mean a
> single <pre/> element.
> 
> In previous usage, we assumed that a space on a line on its own would
> cause the adjacent verbatim paragraphs to be grouped together, but a
> completely blank line would cause the two verbatim paragraphs to be
> split.  As you can see in case (3) above, this does not work.
> 
> It is in fact possible to have adjacent verbatim paragraphs not be
> grouped together.  It involves inserting an empty, zero length
> ordinary paragraph between the two, which can be done using the
> ?=for paragraph? syntax:
> 
>  nbdkit foo \
>  --dump-plugin
> 
>  =for paragraph
> 
>  nbdkit bar
> 
> In HTML output this will be formatted as two <pre/> elements.  Note
> that the blank lines before and after ?=for paragraph? are necessary.
> 
> This commit reformats all existing POD documentation in nbdkit to
> conform.  There are two main changes:
> 
> (a) Lines which contain only whitespace (ie. those we previously used
> to mean ?group these verbatim paragraphs together?) are replaced with
> completely empty lines.
> 
> (b) Completely empty lines occurring between two verbatim paragraphs
> are replaced with ?\n=for paragraph\n\n?, ie. inserting a blank
> ordinary paragraph to stop the verbatim paragraphs from running
> together.
I'm not convinced we should do this automatically. For example, in
<https://libguestfs.org/nbdkit-filter.3.html> below:
> 
> The following commit adds syntax checking to podwrapper to identify
> trailing whitespace in POD files, so that we don't introduce this kind
> of error in future.
> 
> Note that I don't try to unindent the verbatim paragraphs, because
> that looks weird and also makes it harder for us to parse the POD in
> case we needed to in future.
> 
> This commit change was made mechanically using this Perl script:
> 
> use strict;
> 
> foreach my $input (@ARGV) {
>     my $content;
>     { local $/ = undef;
>       open FILE, "<:encoding(UTF-8)", $input or die
"$input: $!";
>       $content = <FILE> }
>     # Verbatim paragraphs separated by empty line, means do not group.
>     $content =~ s/(\n [^\n]*)\n\n /$1\n\n=for paragraph\n\n /g;
>     # Any remaining lines containing only whitespace, group.
>     $content =~ s/\n[ \t]+\n/\n\n/g;
>     rename ($input, "$input.bak");
>     open FILE, ">:encoding(UTF-8)", $input or die
"$input: $!";
>     print FILE $content;
> }
> 
> Thanks: Laszlo Ersek
> See-also:
https://listman.redhat.com/archives/libguestfs/2022-May/thread.html#28902
> ---
>  docs/nbdkit-captive.pod                        |  2 ++
>  docs/nbdkit-filter.pod                         | 14 +++++++++-----
>  docs/nbdkit-plugin.pod                         | 12 +++++++-----
>  docs/nbdkit-probing.pod                        |  4 ++++
>  docs/nbdkit-service.pod                        |  4 ++--
>  docs/nbdkit.pod                                |  2 ++
>  .../checkwrite/nbdkit-checkwrite-filter.pod    |  2 ++
>  filters/ddrescue/nbdkit-ddrescue-filter.pod    |  2 ++
>  filters/delay/nbdkit-delay-filter.pod          |  2 ++
>  filters/ext2/nbdkit-ext2-filter.pod            |  2 ++
>  filters/readahead/nbdkit-readahead-filter.pod  |  2 ++
>  filters/scan/nbdkit-scan-filter.pod            |  2 ++
>  filters/stats/nbdkit-stats-filter.pod          |  8 ++++----
>  filters/swab/nbdkit-swab-filter.pod            |  4 ++++
>  filters/xz/nbdkit-xz-filter.pod                |  2 ++
>  plugins/S3/nbdkit-S3-plugin.pod                |  2 +-
>  plugins/cc/nbdkit-cc-plugin.pod                | 18 +++++++++---------
>  plugins/curl/nbdkit-curl-plugin.pod            |  4 ++--
>  plugins/data/nbdkit-data-plugin.pod            |  8 ++++++++
>  plugins/file/nbdkit-file-plugin.pod            |  2 ++
>  plugins/golang/nbdkit-golang-plugin.pod        |  8 ++++----
>  plugins/guestfs/nbdkit-guestfs-plugin.pod      |  4 ++++
>  plugins/info/nbdkit-info-plugin.pod            |  2 ++
>  plugins/memory/nbdkit-memory-plugin.pod        |  4 ++--
>  plugins/nbd/nbdkit-nbd-plugin.pod              |  4 ++++
>  plugins/ocaml/nbdkit-ocaml-plugin.pod          |  6 ++++--
>  plugins/ondemand/nbdkit-ondemand-plugin.pod    |  2 ++
>  plugins/rust/nbdkit-rust-plugin.pod            |  6 ++++--
>  plugins/sh/nbdkit-sh-plugin.pod                |  4 ++++
>  plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod      |  2 ++
>  30 files changed, 102 insertions(+), 38 deletions(-)
> 
> diff --git a/docs/nbdkit-captive.pod b/docs/nbdkit-captive.pod
> index d41a824d..8fee3913 100644
> --- a/docs/nbdkit-captive.pod
> +++ b/docs/nbdkit-captive.pod
> @@ -7,6 +7,8 @@ reliably cleaned up
>  
>   nbdkit PLUGIN [...] [-e|--exportname EXPORTNAME] --run "CMD ARGS
..."
>  
> +=for paragraph
> +
>   nbdkit --exit-with-parent PLUGIN [...]
>  
>  =head1 DESCRIPTION
> diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod
> index 587b012e..1bf6468a 100644
> --- a/docs/nbdkit-filter.pod
> +++ b/docs/nbdkit-filter.pod
> @@ -5,7 +5,7 @@ nbdkit-filter - how to write nbdkit filters
>  =head1 SYNOPSIS
>  
>   #include <nbdkit-filter.h>
> - 
> +
>   static int
>   myfilter_config (nbdkit_next_config *next, void *nxdata,
>                    const char *key, const char *value)
> @@ -19,13 +19,13 @@ nbdkit-filter - how to write nbdkit filters
>       return next (nxdata, key, value);
>     }
>   }
> - 
> +
>   static struct nbdkit_filter filter = {
>     .name              = "filter",
>     .config            = myfilter_config,
>     /* etc */
>   };
> - 
> +
>   NBDKIT_REGISTER_FILTER(filter)
>  
>  When this has been compiled to a shared library, do:
> @@ -72,7 +72,7 @@ parameters the filter can intercept the C<.config>
method:
>       return next (nxdata, key, value);
>     }
>   }
> - 
> +
>   static struct nbdkit_filter filter = {
>     // ...
>     .config            = myfilter_config,
> @@ -118,7 +118,7 @@ that the filter wants to intercept.
>     .config            = myfilter_config,
>     /* etc */
>   };
> - 
> +
>   NBDKIT_REGISTER_FILTER(filter)
>  
>  The C<.name> field is the name of the filter.  This is the only
field
> @@ -501,6 +501,8 @@ from the layer below.  Without error checking it would
look like this:
>     struct nbdkit_export e;
>     char *name, *desc;
>  
> +=for paragraph
> +
>     exports2 = nbdkit_exports_new ();
>     next_list_exports (nxdata, readonly, exports);
>     for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
The above insertion splits the myfilter_list_exports() code example, which is
currently rendered very nicely in a single verbatim paragraph:

<pre><code> myfilter_list_exports (...)
 {
   size_t i;
   struct nbdkit_exports *exports2;
   struct nbdkit_export e;
   char *name, *desc;

   exports2 = nbdkit_exports_new ();
   next_list_exports (nxdata, readonly, exports);
   for (i = 0; i &lt; nbdkit_exports_count (exports2); ++i) {
     e = nbdkit_get_export (exports2, i);
     name = adjust (e.name);
     desc = adjust (e.desc);
     nbdkit_add_export (exports, name, desc);
     free (name);
     free (desc);
   }
   nbdkit_exports_free (exports2);
 }</code></pre>

into two paragraphs -- for no good reason AFAICT.

I didn't go as far as actually applying this patch and rebuilding nbdkit,
but I did hand-edit the rendered HTML from the website in the Firefox inspector:

<pre><code> myfilter_list_exports (...)
 {
   size_t i;
   struct nbdkit_exports *exports2;
   struct nbdkit_export e;
   char *name, *desc;</code></pre><pre><code>   exports2
= nbdkit_exports_new ();
   next_list_exports (nxdata, readonly, exports);
   for (i = 0; i &lt; nbdkit_exports_count (exports2); ++i) {
     e = nbdkit_get_export (exports2, i);
     name = adjust (e.name);
     desc = adjust (e.desc);
     nbdkit_add_export (exports, name, desc);
     free (name);
     free (desc);
   }
   nbdkit_exports_free (exports2);
 }</code></pre>

and that looks like the attachment shows -- the red bar to the left is broken
up, and there's a white gap between the declarations and the code.

Now if we actually wanted to separate these verbatim paragraphs, this output
would be visually pleasing, so I'm not complaing about that. What I'm
saying is that our current use of completely empty lines is inconsistent;
sometimes it means "split these adjacent verbatim paragraphs apart",
sometimes it means "keep them fused". Therefore we shouldn't
automate the "=for paragraph" insertion.

Thanks
Laszlo

> @@ -948,6 +950,8 @@ from the layer below.  Without error checking it would
look like this:
>     struct nbdkit_extent e;
>     int64_t size;
>  
> +=for paragraph
> +
>     size = next->get_size (next);
>     extents2 = nbdkit_extents_new (offset + shift, size);
>     next->extents (next, count, offset + shift, flags, extents2, err);
> diff --git a/docs/nbdkit-plugin.pod b/docs/nbdkit-plugin.pod
> index bcea900f..383dcffe 100644
> --- a/docs/nbdkit-plugin.pod
> +++ b/docs/nbdkit-plugin.pod
> @@ -6,16 +6,16 @@ nbdkit-plugin - how to write nbdkit plugins
>  
>   #define NBDKIT_API_VERSION 2
>   #include <nbdkit-plugin.h>
> - 
> +
>   #define THREAD_MODEL NBDKIT_THREAD_MODEL_SERIALIZE_ALL_REQUESTS
> - 
> +
>   static void *
>   myplugin_open (void)
>   {
>     /* create a handle ... */
>     return handle;
>   }
> - 
> +
>   static struct nbdkit_plugin plugin = {
>     .name              = "myplugin",
>     .open              = myplugin_open,
> @@ -172,7 +172,7 @@ the plugin:
>   ??????????????           ? close      ?
>   ? close      ?           ??????????????
>   ??????????????
> - 
> +
>                     ?           before nbdkit exits
>                     ?
>           ????????????????????
> @@ -1471,7 +1471,7 @@ passwords from config parameters:
>  For example:
>  
>   char *password = NULL;
> - 
> +
>   static int
>   myplugin_config (const char *key, const char *value)
>   {
> @@ -1946,6 +1946,8 @@ written in Perl called C<foo.pl> might be
installed like this:
>   $ head -1 foo.pl
>   #!/usr/sbin/nbdkit perl
>  
> +=for paragraph
> +
>   $ sudo install -m 0755 foo.pl $plugindir/nbdkit-foo-plugin
>  
>  and then users will be able to run it like this:
> diff --git a/docs/nbdkit-probing.pod b/docs/nbdkit-probing.pod
> index 55e6d193..05be8fbd 100644
> --- a/docs/nbdkit-probing.pod
> +++ b/docs/nbdkit-probing.pod
> @@ -6,10 +6,14 @@ nbdkit-probing - how to probe for nbdkit configuration
and plugins
>  
>   nbdkit --dump-config
>  
> +=for paragraph
> +
>   nbdkit PLUGIN --dump-plugin
>  
>   nbdkit --version
>  
> +=for paragraph
> +
>   nbdkit PLUGIN --version
>  
>   nbdkit --filter=FILTER null --version
> diff --git a/docs/nbdkit-service.pod b/docs/nbdkit-service.pod
> index 03b6ea2d..e3eef6ba 100644
> --- a/docs/nbdkit-service.pod
> +++ b/docs/nbdkit-service.pod
> @@ -31,10 +31,10 @@ containing:
>  
>   [Unit]
>   Description=NBDKit Network Block Device server
> - 
> +
>   [Socket]
>   ListenStream=10809
> - 
> +
>   [Install]
>   WantedBy=sockets.target
>  
> diff --git a/docs/nbdkit.pod b/docs/nbdkit.pod
> index ef3869f7..c5ea9a35 100644
> --- a/docs/nbdkit.pod
> +++ b/docs/nbdkit.pod
> @@ -74,6 +74,8 @@ L<nbdkit-curl-plugin(1)> or
L<nbdkit-ssh-plugin(1)>:
>  
>   nbdkit -r curl https://example.com/disk.img
>  
> +=for paragraph
> +
>   nbdkit ssh host=example.com /var/tmp/disk.img
>  
>  =item *
> diff --git a/filters/checkwrite/nbdkit-checkwrite-filter.pod
b/filters/checkwrite/nbdkit-checkwrite-filter.pod
> index 60f8afa8..04d8c6c5 100644
> --- a/filters/checkwrite/nbdkit-checkwrite-filter.pod
> +++ b/filters/checkwrite/nbdkit-checkwrite-filter.pod
> @@ -31,6 +31,8 @@ filter, and copying from and to nbdkit at the same time:
>   nbdkit -U - --filter=checkwrite data "@32768 1" \
>          --run 'nbdcopy "$uri" "$uri"'
>  
> +=for paragraph
> +
>   nbdkit -U - --filter=checkwrite file disk.img \
>          --run 'nbdcopy "$uri" "$uri"'
>  
> diff --git a/filters/ddrescue/nbdkit-ddrescue-filter.pod
b/filters/ddrescue/nbdkit-ddrescue-filter.pod
> index 601d58fa..eadd392d 100644
> --- a/filters/ddrescue/nbdkit-ddrescue-filter.pod
> +++ b/filters/ddrescue/nbdkit-ddrescue-filter.pod
> @@ -7,6 +7,8 @@ nbdkit-ddrescue-filter - nbdkit filter for serving from
ddrescue dump
>   nbdkit --filter=ddrescue plugin [plugin-args...]
>                                   ddrescue-mapfile=file.map
>  
> +=for paragraph
> +
>   nbdkit --filter=ddrescue file file=file.img ddrescue-mapfile=file.map
>                                 [plugin-args...]
>  
> diff --git a/filters/delay/nbdkit-delay-filter.pod
b/filters/delay/nbdkit-delay-filter.pod
> index 76614736..65c00584 100644
> --- a/filters/delay/nbdkit-delay-filter.pod
> +++ b/filters/delay/nbdkit-delay-filter.pod
> @@ -6,6 +6,8 @@ nbdkit-delay-filter - nbdkit delay filter
>  
>   nbdkit --filter=delay plugin rdelay=SECS wdelay=SECS [plugin-args...]
>  
> +=for paragraph
> +
>   nbdkit --filter=delay plugin rdelay=NNms wdelay=NNms [plugin-args...]
>  
>   nbdkit --filter=delay plugin [plugin-args ...]
> diff --git a/filters/ext2/nbdkit-ext2-filter.pod
b/filters/ext2/nbdkit-ext2-filter.pod
> index c15a2fcb..b2064e8a 100644
> --- a/filters/ext2/nbdkit-ext2-filter.pod
> +++ b/filters/ext2/nbdkit-ext2-filter.pod
> @@ -7,6 +7,8 @@ ext4 filesystems
>  
>   nbdkit --filter=ext2 file fs.img ext2file=/disks/disk.raw
>  
> +=for paragraph
> +
>   nbdkit --filter=ext2 --filter=partition file fs.img \
>      partition=1 ext2file=exportname
>  
> diff --git a/filters/readahead/nbdkit-readahead-filter.pod
b/filters/readahead/nbdkit-readahead-filter.pod
> index 99d64dfb..29d330ac 100644
> --- a/filters/readahead/nbdkit-readahead-filter.pod
> +++ b/filters/readahead/nbdkit-readahead-filter.pod
> @@ -6,6 +6,8 @@ nbdkit-readahead-filter - prefetch data ahead of sequential
reads
>  
>   nbdkit --filter=readahead PLUGIN
>  
> +=for paragraph
> +
>   nbdkit --filter=readahead --filter=cache PLUGIN
>  
>   nbdkit --filter=readahead --filter=cow PLUGIN cow-on-cache=true
> diff --git a/filters/scan/nbdkit-scan-filter.pod
b/filters/scan/nbdkit-scan-filter.pod
> index 2fe9bb80..5a096a78 100644
> --- a/filters/scan/nbdkit-scan-filter.pod
> +++ b/filters/scan/nbdkit-scan-filter.pod
> @@ -7,6 +7,8 @@ nbdkit-scan-filter - scan disk prefetching data ahead of
sequential reads
>   nbdkit --filter=scan PLUGIN [scan-ahead=false] [scan-clock=false]
>                               [scan-forever=true] [scan-size=]NN
>  
> +=for paragraph
> +
>   nbdkit --filter=scan --filter=cache PLUGIN
>  
>   nbdkit --filter=scan --filter=cow PLUGIN cow-on-cache=true
> diff --git a/filters/stats/nbdkit-stats-filter.pod
b/filters/stats/nbdkit-stats-filter.pod
> index 0e89f237..9bf25723 100644
> --- a/filters/stats/nbdkit-stats-filter.pod
> +++ b/filters/stats/nbdkit-stats-filter.pod
> @@ -25,7 +25,7 @@ are written to a file once when nbdkit exits.
>   write: 1088 ops, 0.065065 s, 132.38 MiB, 1.99 GiB/s op, 38.98 MiB/s total
>   trim: 14 ops, 0.002037 s, 25.00 GiB, 12272.95 GiB/s op, 7.36 GiB/s total
>   flush: 5 ops, 0.000002 s, 0 bytes, 0 bytes/s op, 0 bytes/s total
> - 
> +
>   READ request sizes:
>        4096 bytes: 66.2% of requests (96)
>            12 bit aligned: 100.0% (96)
> @@ -41,19 +41,19 @@ are written to a file once when nbdkit exits.
>            17 bit aligned:  71.4% (5)
>            19 bit aligned:  42.9% (3)
>       other sizes: 29.0% of requests (42)
> - 
> +
>   WRITE request sizes:
>      131072 bytes: 97.1% of requests (1056)
>            17 bit aligned: 100.0% (1056)
>            18 bit aligned:  50.0% (528)
>            19+ bit-aligned: 25.0% (264)
>       other sizes:  2.9% of requests (32)
> - 
> +
>   TRIM request sizes:
>   2147483648 bytes: 85.7% of requests (12)
>            24 bit aligned: 100.0% (12)
>       other sizes: 14.3% of requests (2)
> - 
> +
>   ZERO request sizes:
>       (no such requests)
>  
> diff --git a/filters/swab/nbdkit-swab-filter.pod
b/filters/swab/nbdkit-swab-filter.pod
> index 6e036270..e7c15ba7 100644
> --- a/filters/swab/nbdkit-swab-filter.pod
> +++ b/filters/swab/nbdkit-swab-filter.pod
> @@ -58,6 +58,8 @@ This swaps the endianness of each 4 byte word in the
disk, ie:
>  
>    input    0   1   2   3   4   5   6   7
>  
> +=for paragraph
> +
>   output    3   2   1   0   7   6   5   4
>  
>  =item B<swab-bits=64>
> @@ -66,6 +68,8 @@ This swaps the endianness of each 8 byte word in the
disk, ie:
>  
>    input    0   1   2   3   4   5   6   7
>  
> +=for paragraph
> +
>   output    7   6   5   4   3   2   1   0
>  
>  This can be used to make L<nbdkit-pattern-plugin(1)> little endian
> diff --git a/filters/xz/nbdkit-xz-filter.pod
b/filters/xz/nbdkit-xz-filter.pod
> index 88cd569f..8248efb5 100644
> --- a/filters/xz/nbdkit-xz-filter.pod
> +++ b/filters/xz/nbdkit-xz-filter.pod
> @@ -6,6 +6,8 @@ nbdkit-xz-filter - nbdkit xz filter
>  
>   nbdkit --filter=xz file FILENAME.xz
>  
> +=for paragraph
> +
>   nbdkit --filter=xz curl https://example.com/FILENAME.xz
>  
>  =head1 DESCRIPTION
> diff --git a/plugins/S3/nbdkit-S3-plugin.pod
b/plugins/S3/nbdkit-S3-plugin.pod
> index bd978fc1..52188535 100644
> --- a/plugins/S3/nbdkit-S3-plugin.pod
> +++ b/plugins/S3/nbdkit-S3-plugin.pod
> @@ -107,7 +107,7 @@ F<~/.aws/credentials> file.  This takes the form:
>   [default]
>   aws_access_key_id = XXX
>   aws_secret_access_key = YYY
> - 
> +
>   [profile]
>   aws_access_key_id = XXX
>   aws_secret_access_key = YYY
> diff --git a/plugins/cc/nbdkit-cc-plugin.pod
b/plugins/cc/nbdkit-cc-plugin.pod
> index be4019f9..b7099beb 100644
> --- a/plugins/cc/nbdkit-cc-plugin.pod
> +++ b/plugins/cc/nbdkit-cc-plugin.pod
> @@ -136,26 +136,26 @@ All other parameters on the command line are passed
to the plugin.
>   $ nbdkit cc - <<'EOF'
>   #include <stdint.h>
>   #include <string.h>
> - 
> +
>   #define NBDKIT_API_VERSION 2
>   #include <nbdkit-plugin.h>
> - 
> +
>   char data[10*1024*1024];
> - 
> +
>   #define THREAD_MODEL NBDKIT_THREAD_MODEL_PARALLEL
> - 
> +
>   static void *
>   my_open (int readonly)
>   {
>     return NBDKIT_HANDLE_NOT_NEEDED;
>   }
> - 
> +
>   static int64_t
>   my_get_size (void *handle)
>   {
>     return (int64_t) sizeof (data);
>   }
> - 
> +
>   static int
>   my_pread (void *handle, void *buf,
>             uint32_t count, uint64_t offset,
> @@ -164,7 +164,7 @@ All other parameters on the command line are passed to
the plugin.
>     memcpy (buf, data+offset, count);
>     return 0;
>   }
> - 
> +
>   static int
>   my_pwrite (void *handle, const void *buf,
>              uint32_t count, uint64_t offset,
> @@ -173,7 +173,7 @@ All other parameters on the command line are passed to
the plugin.
>     memcpy (data+offset, buf, count);
>     return 0;
>   }
> - 
> +
>   static struct nbdkit_plugin plugin = {
>     .name              = "myplugin",
>     .open              = my_open,
> @@ -181,7 +181,7 @@ All other parameters on the command line are passed to
the plugin.
>     .pread             = my_pread,
>     .pwrite            = my_pwrite,
>   };
> - 
> +
>   NBDKIT_REGISTER_PLUGIN(plugin)
>   EOF
>  
> diff --git a/plugins/curl/nbdkit-curl-plugin.pod
b/plugins/curl/nbdkit-curl-plugin.pod
> index fc422ca2..e422aca7 100644
> --- a/plugins/curl/nbdkit-curl-plugin.pod
> +++ b/plugins/curl/nbdkit-curl-plugin.pod
> @@ -403,7 +403,7 @@ I<--insecure> and C<sslverify=false>.
>   DS=datastore1
>   GUEST=guest-name
>  
URL="https://$SERVER/folder/$GUEST/$GUEST-flat.vmdk?dcPath=$DCPATH&dsName=$DS"
> - 
> +
>   nbdkit curl "$URL" \
>          cookie-script='
>              curl --head -s --insecure -u root:password "$url" |
> @@ -442,7 +442,7 @@ check they are working.  To run nbdkit:
>   IMAGE=library/fedora
>   BLOBSUM=`/tmp/blobsum.sh`
>   URL="https://registry-1.docker.io/v2/$IMAGE/blobs/$BLOBSUM"
> - 
> +
>   nbdkit curl "$URL" \
>          header-script=' printf "Authorization: Bearer ";
/tmp/auth.sh ' \
>          header-script-renew=200 \
> diff --git a/plugins/data/nbdkit-data-plugin.pod
b/plugins/data/nbdkit-data-plugin.pod
> index 6e52394a..32f52fde 100644
> --- a/plugins/data/nbdkit-data-plugin.pod
> +++ b/plugins/data/nbdkit-data-plugin.pod
> @@ -7,9 +7,13 @@ nbdkit-data-plugin - nbdkit plugin for serving data from
the command line
>   nbdkit data [data=]'0 1 2 3 @0x1fe 0x55 0xaa'
>               [size=SIZE] [allocator=sparse|malloc|zstd]
>  
> +=for paragraph
> +
>   nbdkit data base64='aGVsbG8gbmJka2l0IHVzZXI='
>               [size=SIZE] [allocator=sparse|malloc|zstd]
>  
> +=for paragraph
> +
>   nbdkit data raw='binary_data'
>               [size=SIZE] [allocator=sparse|malloc|zstd]
>  
> @@ -351,9 +355,13 @@ expressions.  These are all equivalent:
>  
>   nbdkit data '$pattern*16' pattern='0x55 0xAA'
>  
> +=for paragraph
> +
>   export pattern='0x55 0xAA'
>   nbdkit data '$pattern*16'
>  
> +=for paragraph
> +
>   nbdkit data '( 0x55 0xAA )*16'
>  
>  =item B<#> COMMENT
> diff --git a/plugins/file/nbdkit-file-plugin.pod
b/plugins/file/nbdkit-file-plugin.pod
> index b95e7349..49c33066 100644
> --- a/plugins/file/nbdkit-file-plugin.pod
> +++ b/plugins/file/nbdkit-file-plugin.pod
> @@ -7,6 +7,8 @@ nbdkit-file-plugin - nbdkit file plugin
>   nbdkit file [file=]FILENAME
>               [cache=default|none] [fadvise=normal|random|sequential]
>  
> +=for paragraph
> +
>   nbdkit file dir=DIRECTORY
>  
>  =head1 DESCRIPTION
> diff --git a/plugins/golang/nbdkit-golang-plugin.pod
b/plugins/golang/nbdkit-golang-plugin.pod
> index eb1e6251..34f9a6eb 100644
> --- a/plugins/golang/nbdkit-golang-plugin.pod
> +++ b/plugins/golang/nbdkit-golang-plugin.pod
> @@ -50,7 +50,7 @@ C<nbdkit.Connection> structs respectively:
>   type MyPlugin struct {
>           nbdkit.Plugin
>   }
> - 
> +
>   type MyConnection struct {
>           nbdkit.Connection
>   }
> @@ -65,12 +65,12 @@ should return a new instance of your connection struct.
For example:
>   func (p *MyPlugin) Load() {
>           // global callback used for initializing the plugin
>   }
> - 
> +
>   func (p *MyPlugin) Open(readonly bool) (nbdkit.ConnectionInterface,
error) {
>           // new client has connected
>           return &MyConnection{}, nil
>   }
> - 
> +
>   func (c *MyConnection) GetSize() (uint64, error) {
>           // called per-client
>           return virtual_size, nil
> @@ -109,7 +109,7 @@ C<Zero> (C<CanZero>).
>   func (c *MyConnection) CanWrite() (bool, error) {
>           return true, nil
>   }
> - 
> +
>   func (c *MyConnection) PWrite(buf []byte, offset uint64,
>          flags uint32) error {
>           // ...
> diff --git a/plugins/guestfs/nbdkit-guestfs-plugin.pod
b/plugins/guestfs/nbdkit-guestfs-plugin.pod
> index b3d9a872..fc1c6025 100644
> --- a/plugins/guestfs/nbdkit-guestfs-plugin.pod
> +++ b/plugins/guestfs/nbdkit-guestfs-plugin.pod
> @@ -138,6 +138,8 @@ needed.
>  
>   nbdkit guestfs disk=disk.img export=/dev/sda1
>  
> +=for paragraph
> +
>   nbdkit guestfs disk=disk.img export=/dev/VG/LV
>  
>  Use L<virt-filesystems(1)> to find out what devices, partitions,
LVs,
> @@ -152,6 +154,8 @@ needed.
>  
>   nbdkit -r guestfs domain=Guest export=/dev/sda1
>  
> +=for paragraph
> +
>   nbdkit -r guestfs domain=Guest export=/dev/VG/LV
>  
>  =head2 Exporting a file inside a disk image
> diff --git a/plugins/info/nbdkit-info-plugin.pod
b/plugins/info/nbdkit-info-plugin.pod
> index 8ed9db9a..4bc4aaef 100644
> --- a/plugins/info/nbdkit-info-plugin.pod
> +++ b/plugins/info/nbdkit-info-plugin.pod
> @@ -43,6 +43,8 @@ characters is created.  We then display the contents:
>   print("buf = %r" % buf)
>   EOF
>  
> +=for paragraph
> +
>   size = 5
>   buf = b"hello"
>  
> diff --git a/plugins/memory/nbdkit-memory-plugin.pod
b/plugins/memory/nbdkit-memory-plugin.pod
> index 8f0c223f..9e546c3d 100644
> --- a/plugins/memory/nbdkit-memory-plugin.pod
> +++ b/plugins/memory/nbdkit-memory-plugin.pod
> @@ -85,11 +85,11 @@ the memory plugin, use L<qemu-img(1)> or
L<nbdcopy(1)>:
>  
>   $ rm -f pid
>   $ nbdkit -P pid memory 10G
> - 
> +
>  Wait for nbdkit to become ready to accept connections:
>  
>   $ while [ ! -f pid ]; do sleep 1; done
> - 
> +
>  Preload Fedora disk image using qemu-img:
>  
>   $ virt-builder fedora-28 --size=10G
> diff --git a/plugins/nbd/nbdkit-nbd-plugin.pod
b/plugins/nbd/nbdkit-nbd-plugin.pod
> index 484304ee..e907a10b 100644
> --- a/plugins/nbd/nbdkit-nbd-plugin.pod
> +++ b/plugins/nbd/nbdkit-nbd-plugin.pod
> @@ -260,6 +260,8 @@ that the old server exits.
>     nbdkit --exit-with-parent --tls=require nbd socket=$sock &
>     exec /path/to/oldserver --socket=$sock )
>  
> +=for paragraph
> +
>   ??????????????   TLS    ??????????  plaintext  ??????????????
>   ? new client ? ?????????? nbdkit ? ????????????? old server ?
>   ??????????????   TCP    ??????????    Unix     ??????????????
> @@ -298,6 +300,8 @@ limited to a Unix socket on the local machine.
>   nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require
\
>    --run '/path/to/oldclient --socket=$unixsocket'
>  
> +=for paragraph
> +
>   ??????????????  plaintext  ??????????   TLS    ??????????????
>   ? old client ? ????????????? nbdkit ? ?????????? new server ?
>   ??????????????    Unix     ??????????   TCP    ??????????????
> diff --git a/plugins/ocaml/nbdkit-ocaml-plugin.pod
b/plugins/ocaml/nbdkit-ocaml-plugin.pod
> index 22048633..38e605d9 100644
> --- a/plugins/ocaml/nbdkit-ocaml-plugin.pod
> +++ b/plugins/ocaml/nbdkit-ocaml-plugin.pod
> @@ -6,6 +6,8 @@ nbdkit-ocaml-plugin - writing nbdkit plugins in OCaml
>  
>   nbdkit /path/to/plugin.so [arguments...]
>  
> +=for paragraph
> +
>   nbdkit plugin [arguments...]
>  
>  =head1 DESCRIPTION
> @@ -77,13 +79,13 @@ handle struct in your plugin:
>     h_id : int; (* this is just an example field *)
>     h_readonly : bool;
>   }
> - 
> +
>   let id = ref 0
>   let myplugin_open readonly >     (* return a newly allocated handle *)
>     incr id;
>     { h_id = !id; h_readonly = readonly }
> - 
> +
>   let myplugin_get_size handle >     printf "handle ID = %d\n"
handle.h_id;
>     (* ... *)
> diff --git a/plugins/ondemand/nbdkit-ondemand-plugin.pod
b/plugins/ondemand/nbdkit-ondemand-plugin.pod
> index cccaa1d9..a2a14ac1 100644
> --- a/plugins/ondemand/nbdkit-ondemand-plugin.pod
> +++ b/plugins/ondemand/nbdkit-ondemand-plugin.pod
> @@ -96,6 +96,8 @@ commands such as these (note the different export names):
>   nbd-client server /dev/nbd0 -N export1
>   mount /dev/nbd0 /mnt
>  
> +=for paragraph
> +
>   guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda
>  
>   qemu-img info nbd:localhost:10809:exportname=export2
> diff --git a/plugins/rust/nbdkit-rust-plugin.pod
b/plugins/rust/nbdkit-rust-plugin.pod
> index 9e3ef10e..114e6947 100644
> --- a/plugins/rust/nbdkit-rust-plugin.pod
> +++ b/plugins/rust/nbdkit-rust-plugin.pod
> @@ -28,16 +28,18 @@ Your Rust code should define a public implementation of
the C<Server> trait,
>  and register it using the C<plugin!> macro.
>  
>   use nbdkit::*;
> - 
> +
>   #[derive(Default)]
>   struct MyPlugin {
>       // ...
>   }
> - 
> +
>   impl Server for MyPlugin {
>       // ...
>   }
>  
> +=for paragraph
> +
>   plugin!(MyPlugin {write_at, trim, ...});
>  
>  =head2 Compiling a Rust nbdkit plugin
> diff --git a/plugins/sh/nbdkit-sh-plugin.pod
b/plugins/sh/nbdkit-sh-plugin.pod
> index aede1c65..2a55fdc9 100644
> --- a/plugins/sh/nbdkit-sh-plugin.pod
> +++ b/plugins/sh/nbdkit-sh-plugin.pod
> @@ -6,6 +6,8 @@ nbdkit-sh-plugin - nbdkit shell, script or executable
plugin
>  
>   nbdkit sh /path/to/script [arguments...]
>  
> +=for paragraph
> +
>   nbdkit sh - <<'EOF'
>   ... shell script ...
>   EOF
> @@ -73,6 +75,8 @@ parameter is always the method name.  For example:
>                     ?      ??? key ($2)
>                 method ($1)
>  
> +=for paragraph
> +
>   /path/to/script pread <handle> <count> <offset>
>                     ?       ?       ?       ?
>                     ?       ?       ?       ?? offset in bytes ($4)
> diff --git a/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
b/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
> index 9cecad34..b098f2ab 100644
> --- a/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
> +++ b/plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod
> @@ -6,6 +6,8 @@ nbdkit-tmpdisk-plugin - create a fresh temporary filesystem
for each client
>  
>   nbdkit tmpdisk [size=]SIZE [type=ext4|xfs|vfat|...] [label=LABEL]
>  
> +=for paragraph
> +
>   nbdkit tmpdisk [size=]SIZE command=COMMAND [VAR=VALUE ...]
>  
>  =head1 DESCRIPTION
> 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screenshot from 2022-05-24 15-13-51.png
Type: image/png
Size: 64225 bytes
Desc: not available
URL:
<http://listman.redhat.com/archives/libguestfs/attachments/20220524/8cc327eb/attachment.png>

Libguestfs - May 2022 - [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs

[Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs

[Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs