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(-)