Re: [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(-)