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 run together, whether or not there is a line containing whitespace between the paragraphs or not. 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 blank line 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 <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) Lines which contain only whitespace (ie. those we previously used to mean “group these verbatim paragraphs together”) are replaced with completely empty lines. (b) Completely empty lines occurring between two verbatim paragraphs are replaced with “\n=for paragraph\n\n”, ie. inserting a blank ordinary paragraph to stop the verbatim paragraphs from running together. 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 commit change was made mechanically using this Perl script: 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. $content =~ s/(\n [^\n]*)\n\n /$1\n\n=for paragraph\n\n /g; # 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 | 4 ++++ 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 | 2 ++ filters/ext2/nbdkit-ext2-filter.pod | 2 ++ filters/readahead/nbdkit-readahead-filter.pod | 2 ++ filters/scan/nbdkit-scan-filter.pod | 2 ++ 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 | 2 ++ plugins/rust/nbdkit-rust-plugin.pod | 6 ++++-- plugins/sh/nbdkit-sh-plugin.pod | 4 ++++ plugins/tmpdisk/nbdkit-tmpdisk-plugin.pod | 2 ++ 30 files changed, 102 insertions(+), 38 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 587b012e..1bf6468a 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 @@ -501,6 +501,8 @@ from the layer below. Without error checking it would look like this: struct nbdkit_export e; char *name, *desc; +=for paragraph + exports2 = nbdkit_exports_new (); next_list_exports (nxdata, readonly, exports); for (i = 0; i < nbdkit_exports_count (exports2); ++i) { @@ -948,6 +950,8 @@ from the layer below. Without error checking it would look like this: struct nbdkit_extent e; int64_t size; +=for paragraph + 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..05be8fbd 100644 --- a/docs/nbdkit-probing.pod +++ b/docs/nbdkit-probing.pod @@ -6,10 +6,14 @@ nbdkit-probing - how to probe for nbdkit configuration and plugins nbdkit --dump-config +=for paragraph + nbdkit PLUGIN --dump-plugin nbdkit --version +=for paragraph + nbdkit PLUGIN --version nbdkit --filter=FILTER null --version 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..65c00584 100644 --- a/filters/delay/nbdkit-delay-filter.pod +++ b/filters/delay/nbdkit-delay-filter.pod @@ -6,6 +6,8 @@ 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...] nbdkit --filter=delay plugin [plugin-args ...] 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..29d330ac 100644 --- a/filters/readahead/nbdkit-readahead-filter.pod +++ b/filters/readahead/nbdkit-readahead-filter.pod @@ -6,6 +6,8 @@ nbdkit-readahead-filter - prefetch data ahead of sequential reads nbdkit --filter=readahead PLUGIN +=for paragraph + nbdkit --filter=readahead --filter=cache PLUGIN nbdkit --filter=readahead --filter=cow PLUGIN cow-on-cache=true diff --git a/filters/scan/nbdkit-scan-filter.pod b/filters/scan/nbdkit-scan-filter.pod index 2fe9bb80..5a096a78 100644 --- a/filters/scan/nbdkit-scan-filter.pod +++ b/filters/scan/nbdkit-scan-filter.pod @@ -7,6 +7,8 @@ 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 nbdkit --filter=scan --filter=cow PLUGIN cow-on-cache=true 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..a2a14ac1 100644 --- a/plugins/ondemand/nbdkit-ondemand-plugin.pod +++ b/plugins/ondemand/nbdkit-ondemand-plugin.pod @@ -96,6 +96,8 @@ 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 qemu-img info nbd:localhost:10809:exportname=export2 diff --git a/plugins/rust/nbdkit-rust-plugin.pod b/plugins/rust/nbdkit-rust-plugin.pod index 9e3ef10e..114e6947 100644 --- a/plugins/rust/nbdkit-rust-plugin.pod +++ b/plugins/rust/nbdkit-rust-plugin.pod @@ -28,16 +28,18 @@ 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 { // ... } +=for paragraph + 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

On Tue, May 24, 2022 at 03:20:19PM +0200, Laszlo Ersek wrote: ... Yup, that's wrong (although it was also wrong before). ... Yup, that's what is supposed to happen for logically separate blocks, but not in this particular case. The alternative is going to be pretty tedious though, and I should think more error-prone. How about fixing this particular problem in a new, prior commit, then applying the perl script again, which this time would change the space to an empty line and wouldn't insert "=for paragraph"? Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com libguestfs lets you edit virtual machines. Supports shell scripting, bindings from many languages. http://libguestfs.org

On 05/21/22 16:09, Richard W.M. Jones wrote: Acked-by: Laszlo Ersek <lersek(a)redhat.com&gt;