[Libguestfs] [PATCH nbdkit 1/2] docs: Fix POD verbatim paragraphs
Laszlo Ersek
lersek at redhat.com
Tue May 24 13:20:19 UTC 2022
On 05/21/22 16:09, 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 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.
I'm not convinced we should do this automatically. For example, in <https://libguestfs.org/nbdkit-filter.3.html> below:
>
> 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) {
The above insertion splits the myfilter_list_exports() code example, which is currently rendered very nicely in a single verbatim paragraph:
<pre><code> myfilter_list_exports (...)
{
size_t i;
struct nbdkit_exports *exports2;
struct nbdkit_export e;
char *name, *desc;
exports2 = nbdkit_exports_new ();
next_list_exports (nxdata, readonly, exports);
for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
e = nbdkit_get_export (exports2, i);
name = adjust (e.name);
desc = adjust (e.desc);
nbdkit_add_export (exports, name, desc);
free (name);
free (desc);
}
nbdkit_exports_free (exports2);
}</code></pre>
into two paragraphs -- for no good reason AFAICT.
I didn't go as far as actually applying this patch and rebuilding nbdkit, but I did hand-edit the rendered HTML from the website in the Firefox inspector:
<pre><code> myfilter_list_exports (...)
{
size_t i;
struct nbdkit_exports *exports2;
struct nbdkit_export e;
char *name, *desc;</code></pre><pre><code> exports2 = nbdkit_exports_new ();
next_list_exports (nxdata, readonly, exports);
for (i = 0; i < nbdkit_exports_count (exports2); ++i) {
e = nbdkit_get_export (exports2, i);
name = adjust (e.name);
desc = adjust (e.desc);
nbdkit_add_export (exports, name, desc);
free (name);
free (desc);
}
nbdkit_exports_free (exports2);
}</code></pre>
and that looks like the attachment shows -- the red bar to the left is broken up, and there's a white gap between the declarations and the code.
Now if we actually wanted to separate these verbatim paragraphs, this output would be visually pleasing, so I'm not complaing about that. What I'm saying is that our current use of completely empty lines is inconsistent; sometimes it means "split these adjacent verbatim paragraphs apart", sometimes it means "keep them fused". Therefore we shouldn't automate the "=for paragraph" insertion.
Thanks
Laszlo
> @@ -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
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screenshot from 2022-05-24 15-13-51.png
Type: image/png
Size: 64225 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20220524/8cc327eb/attachment.png>
More information about the Libguestfs
mailing list