thr3ads.net - Libguestfs - [Libguestfs] [PATCH nbdkit 2/2] docs: Enhance podwrapper to detect trailing whitespace [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 0/2] docs: Fix POD verbatim paragraphs

Fix POD verbatim paragraphs in nbdkit, per discussion last week.
If this is right, I'll roll out something similar to other projects.

Rich.

Richard W.M. Jones

2022-May-21 14:09 UTC

head link

[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

Richard W.M. Jones

2022-May-21 14:09 UTC

head link

[Libguestfs] [PATCH nbdkit 2/2] docs: Enhance podwrapper to detect trailing whitespace

Now that trailing whitespace should no longer appear in POD files,
enhance podwrapper to detect this and error out.

I had to modify podwrapper so it doesn't introduce trailing whitespace
when it encounters a blank line in a --verbatim include.

I also fixed an instance of unwanted trailing whitespace.
---
 docs/nbdkit-release-notes-1.16.pod |  2 +-
 podwrapper.pl.in                   | 11 ++++++++---
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/nbdkit-release-notes-1.16.pod
b/docs/nbdkit-release-notes-1.16.pod
index 7e8d76fa..5334e33b 100644
--- a/docs/nbdkit-release-notes-1.16.pod
+++ b/docs/nbdkit-release-notes-1.16.pod
@@ -17,7 +17,7 @@ to the fixed versions is highly recommended.  The new
 L<nbdkit-security(1)> man page contains an up to date list of past
 security issues.
 
-=head3 CVE-2019-14850 
+=head3 CVE-2019-14850
 denial of service due to premature opening of back-end connection
 
 See the full announcement and links to mitigation, tests and fixes
diff --git a/podwrapper.pl.in b/podwrapper.pl.in
index bd0cf3ee..e28020a0 100755
--- a/podwrapper.pl.in
+++ b/podwrapper.pl.in
@@ -286,6 +286,10 @@ die "$progname: $input: is not valid utf8" unless
utf8::is_utf8 ($content);
 die "$progname: $input: =encoding must not be present in input\n"
     if $content =~ /^=encoding/m;
 
+# Don't permit trailing whitespace.
+die "$progname: $input: trailing whitespace in input\n"
+    if $content =~ /[ \t]$/m;
+
 # We may add an encoding line, but this breaks RHEL 6-era Pod::Simple
 # with the error "Cannot decode string with wide characters".
 $content =~ s/^=(.*)/\n=encoding utf8\n\n=$1/m
@@ -576,14 +580,15 @@ sub read_whole_file
 sub read_verbatim_file
 {
     my $input = shift;
-    my $r = "";
+    my @r = ();
 
     open FILE, "<:encoding(UTF-8)", $input or die "$progname:
$input: $!";
     while (<FILE>) {
-        $r .= " $_";
+        chomp;
+        if (length) { push @r, " $_" } else { push @r, "" }
     }
     close FILE;
-    $r;
+    return join ("\n", @r) . "\n";
 }
 
 =head1 SEE ALSO
-- 
2.35.1

Eric Blake

2022-May-24 12:51 UTC

head link

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

On Sat, May 21, 2022 at 03:09:31PM +0100, Richard W.M. Jones
wrote:> Fix POD verbatim paragraphs in nbdkit, per discussion last week.
> If this is right, I'll roll out something similar to other projects.
Both patches look right to me.

Acked-by: Eric Blake <eblake at redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Libguestfs - May 2022 - [PATCH nbdkit 2/2] docs: Enhance podwrapper to detect trailing whitespace

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

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

[Libguestfs] [PATCH nbdkit 2/2] docs: Enhance podwrapper to detect trailing whitespace

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