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

[Laszlo Ersek]

On 05/24/22 16:16, 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 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(-)

Acked-by: Laszlo Ersek <lersek at redhat.com>