thr3ads.net - Libguestfs - [Libguestfs] [PATCH nbdkit v2 0/5] 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-24 14:16 UTC

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

v1 was here:
https://listman.redhat.com/archives/libguestfs/2022-May/thread.html#28934

v2:

 - Patches 1-3 are new.  They fix verbatim grouping and whitespace in
   existing documentation.

 - Patch 4 (was patch 1): I fixed the Perl script since it didn't work
   if you had multiple adjacent non-grouped verbatim paragraphs, as
   you find for example on this page:

  
https://gitlab.com/nbdkit/nbdkit/-/blob/b2612d2c3e24bb40c3cc76ef407d3b46df449dc1/docs/nbdkit-probing.pod#L7-L15

   I reran the new Perl script which now breaks up verbatim paragraphs
   these correctly, and also corrects the corrections in patches 1-3.

 - Patch 5 (was patch 2).  The same, except I moved the logically
   separate docs fix hunk into a new patch.  This should make cherry
   picking into other projects easier.

Rich.

Richard W.M. Jones

2022-May-24 14:16 UTC

head link

[Libguestfs] [PATCH nbdkit v2 1/5] docs: Fix whitespace to logically group C code examples together

Logically group the C code examples together into a single verbatim
section.  Note that a following commit will correct this one.

Fixes: commit 4ca66f70a5865efbad67d719ba84950ddafefc01
Fixes: commit d4c58f93d0589c522d5a3422e61ba7fde1c64255
Thanks: Laszlo Ersek
---
 docs/nbdkit-filter.pod | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/nbdkit-filter.pod b/docs/nbdkit-filter.pod
index 587b012e..416d6fe6 100644
--- a/docs/nbdkit-filter.pod
+++ b/docs/nbdkit-filter.pod
@@ -500,7 +500,7 @@ from the layer below.  Without error checking it would look
like this:
    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 < nbdkit_exports_count (exports2); ++i) {
@@ -947,7 +947,7 @@ from the layer below.  Without error checking it would look
like this:
    struct nbdkit_extents *extents2;
    struct nbdkit_extent e;
    int64_t size;
-
+ 
    size = next->get_size (next);
    extents2 = nbdkit_extents_new (offset + shift, size);
    next->extents (next, count, offset + shift, flags, extents2, err);
-- 
2.35.1

Richard W.M. Jones

2022-May-24 14:16 UTC

head link

[Libguestfs] [PATCH nbdkit v2 2/5] rust: Logically group example code

Fixes: commit 666ec24437932b27b393f7670ec0ecc5f11550bc
Thanks: Laszlo Ersek
---
 plugins/rust/nbdkit-rust-plugin.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/rust/nbdkit-rust-plugin.pod
b/plugins/rust/nbdkit-rust-plugin.pod
index 9e3ef10e..ff9d9c09 100644
--- a/plugins/rust/nbdkit-rust-plugin.pod
+++ b/plugins/rust/nbdkit-rust-plugin.pod
@@ -37,7 +37,7 @@ and register it using the C<plugin!> macro.
  impl Server for MyPlugin {
      // ...
  }
-
+ 
  plugin!(MyPlugin {write_at, trim, ...});
 
 =head2 Compiling a Rust nbdkit plugin
-- 
2.35.1

Richard W.M. Jones

2022-May-24 14:16 UTC

head link

[Libguestfs] [PATCH nbdkit v2 3/5] docs: Remove trailing whitespace from POD file

Fixes: commit 7d96ec5136c778e54fa27c70b2ca4b4f1456a706
---
 docs/nbdkit-release-notes-1.16.pod | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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
-- 
2.35.1

Richard W.M. Jones

2022-May-24 14:16 UTC

head link

[Libguestfs] [PATCH nbdkit v2 4/5] 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 grouped together into a single preformatted
block of output, whether or not there is a line containing whitespace
between the paragraphs.  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 empty line (no whitespace) 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 adjacent <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) Completely empty lines occurring between two verbatim paragraphs
are replaced with ?\n=for paragraph\n\n?, which as explained above
stops the verbatim paragraphs from running together.

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

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 change was made mechanically using this Perl script:

 #!/usr/bin/perl -w
 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.
    my $oldcontent;
    do {
        $oldcontent = $content;
        $content =~ s/(\n [^\n]*)\n\n /$1\n\n=for paragraph\n\n /g;
    } until ($oldcontent eq $content);
    # 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                        |  8 ++++++++
 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          |  4 ++++
 filters/ext2/nbdkit-ext2-filter.pod            |  2 ++
 filters/readahead/nbdkit-readahead-filter.pod  |  4 ++++
 filters/scan/nbdkit-scan-filter.pod            |  4 ++++
 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    |  4 ++++
 plugins/rust/nbdkit-rust-plugin.pod            |  6 +++---
 plugins/sh/nbdkit-sh-plugin.pod                |  4 ++++
 plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod      |  2 ++
 30 files changed, 111 insertions(+), 41 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 416d6fe6..4ce5bda0 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
@@ -500,7 +500,7 @@ from the layer below.  Without error checking it would look
like this:
    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 < nbdkit_exports_count (exports2); ++i) {
@@ -947,7 +947,7 @@ from the layer below.  Without error checking it would look
like this:
    struct nbdkit_extents *extents2;
    struct nbdkit_extent e;
    int64_t size;
- 
+
    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..2bed85b8 100644
--- a/docs/nbdkit-probing.pod
+++ b/docs/nbdkit-probing.pod
@@ -6,12 +6,20 @@ nbdkit-probing - how to probe for nbdkit configuration and
plugins
 
  nbdkit --dump-config
 
+=for paragraph
+
  nbdkit PLUGIN --dump-plugin
 
+=for paragraph
+
  nbdkit --version
 
+=for paragraph
+
  nbdkit PLUGIN --version
 
+=for paragraph
+
  nbdkit --filter=FILTER null --version
 
 =head1 DESCRIPTION
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..0e75f7fa 100644
--- a/filters/delay/nbdkit-delay-filter.pod
+++ b/filters/delay/nbdkit-delay-filter.pod
@@ -6,8 +6,12 @@ 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...]
 
+=for paragraph
+
  nbdkit --filter=delay plugin [plugin-args ...]
           delay-read=(SECS|NNms)
           delay-write=(SECS|NNms)
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..383fff37 100644
--- a/filters/readahead/nbdkit-readahead-filter.pod
+++ b/filters/readahead/nbdkit-readahead-filter.pod
@@ -6,8 +6,12 @@ nbdkit-readahead-filter - prefetch data ahead of sequential
reads
 
  nbdkit --filter=readahead PLUGIN
 
+=for paragraph
+
  nbdkit --filter=readahead --filter=cache PLUGIN
 
+=for paragraph
+
  nbdkit --filter=readahead --filter=cow PLUGIN cow-on-cache=true
 
 =head1 DESCRIPTION
diff --git a/filters/scan/nbdkit-scan-filter.pod
b/filters/scan/nbdkit-scan-filter.pod
index 2fe9bb80..b0438be6 100644
--- a/filters/scan/nbdkit-scan-filter.pod
+++ b/filters/scan/nbdkit-scan-filter.pod
@@ -7,8 +7,12 @@ 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
 
+=for paragraph
+
  nbdkit --filter=scan --filter=cow PLUGIN cow-on-cache=true
 
 =head1 DESCRIPTION
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..5ad0cf93 100644
--- a/plugins/ondemand/nbdkit-ondemand-plugin.pod
+++ b/plugins/ondemand/nbdkit-ondemand-plugin.pod
@@ -96,8 +96,12 @@ 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
 
+=for paragraph
+
  qemu-img info nbd:localhost:10809:exportname=export2
 
 On the server you would see two filesystems created:
diff --git a/plugins/rust/nbdkit-rust-plugin.pod
b/plugins/rust/nbdkit-rust-plugin.pod
index ff9d9c09..2c1795be 100644
--- a/plugins/rust/nbdkit-rust-plugin.pod
+++ b/plugins/rust/nbdkit-rust-plugin.pod
@@ -28,16 +28,16 @@ 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 {
      // ...
  }
- 
+
  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-24 14:17 UTC

head link

[Libguestfs] [PATCH nbdkit v2 5/5] 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.

Acked-by: Laszlo Ersek <lersek at redhat.com>
Acked-by: Eric Blake <eblake at redhat.com>
---
 podwrapper.pl.in | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

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 14:32 UTC

head link

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

On Tue, May 24, 2022 at 03:16:55PM +0100, Richard W.M. Jones
wrote:> v1 was here:
> https://listman.redhat.com/archives/libguestfs/2022-May/thread.html#28934
> 
> v2:
> 
>  - Patches 1-3 are new.  They fix verbatim grouping and whitespace in
>    existing documentation.
Nice; and I agree with doing it separately (even if they cause churn
later in the series), for ease of backporting.
> 
>  - Patch 4 (was patch 1): I fixed the Perl script since it didn't work
>    if you had multiple adjacent non-grouped verbatim paragraphs, as
>    you find for example on this page:
> 
>   
https://gitlab.com/nbdkit/nbdkit/-/blob/b2612d2c3e24bb40c3cc76ef407d3b46df449dc1/docs/nbdkit-probing.pod#L7-L15
> 
>    I reran the new Perl script which now breaks up verbatim paragraphs
>    these correctly, and also corrects the corrections in patches 1-3.
> 
>  - Patch 5 (was patch 2).  The same, except I moved the logically
>    separate docs fix hunk into a new patch.  This should make cherry
>    picking into other projects easier.
Series: 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 v2 0/5] docs: Fix POD verbatim paragraphs

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

[Libguestfs] [PATCH nbdkit v2 1/5] docs: Fix whitespace to logically group C code examples together

[Libguestfs] [PATCH nbdkit v2 2/5] rust: Logically group example code

[Libguestfs] [PATCH nbdkit v2 3/5] docs: Remove trailing whitespace from POD file

[Libguestfs] [PATCH nbdkit v2 4/5] docs: Fix POD verbatim paragraphs

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

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