Laszlo Ersek
2022-May-25 05:52 UTC
[Libguestfs] [PATCH nbdkit v2 4/5] docs: Fix POD verbatim paragraphs
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>
Richard W.M. Jones
2022-May-25 08:53 UTC
[Libguestfs] [PATCH nbdkit v2 4/5] docs: Fix POD verbatim paragraphs
Thanks - the series was pushed in: b2612d2c..43b341b0 master -> master Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com Fedora Windows cross-compiler. Compile Windows programs, test, and build Windows installers. Over 100 libraries supported. http://fedoraproject.org/wiki/MinGW