Re: [Qemu-devel] [PATCH v2 04/22] qemu-nbd: Enhance man page

["Richard W.M. Jones" <rjones@redhat.com>]

On Sat, Dec 15, 2018 at 07:53:06AM -0600, Eric Blake wrote:
> Document some useful qemu-nbd command lines. Mention some restrictions
> on particular options, like -p being only for MBR images, or -c/-d
> being Linux-only.  Update some text given the recent change to no
> longer serve oldstyle protocol (missed in commit 7f7dfe2a).  Also,
> consistently use trailing '.' in describing options.
> 
> Signed-off-by: Eric Blake <eblake@redhat.com>
> 
> ---
> v2: new patch
> ---
>  qemu-nbd.texi | 85 +++++++++++++++++++++++++++++++++++++++------------
>  1 file changed, 66 insertions(+), 19 deletions(-)
> 
> diff --git a/qemu-nbd.texi b/qemu-nbd.texi
> index 9a84e81eed9..0e24c2801ee 100644
> --- a/qemu-nbd.texi
> +++ b/qemu-nbd.texi
> @@ -8,7 +8,10 @@
> 
>  @c man begin DESCRIPTION
> 
> -Export a QEMU disk image using the NBD protocol.
> +Provide access to various QEMU NBD features.  Most commonly used to
> +export a QEMU disk image using the NBD protocol as a server, but can
> +also be used (on Linux) to manage kernel bindings of a /dev/nbdX
> +block device to a QEMU server.

This is only a minor quibble, but I thought the original text was a
good summary, and only needs additional paragraphs describing the more
minor use cases.  Thus the description would become by the end of the
patch series:

  DESCRIPTION

  Export a QEMU disk image using the NBD protocol.

  Other uses:
  * (On Linux) bind /dev/nbdX block device to a QEMU server.
  * As a client to query exports of a remote NBD server.

> +@c man begin EXAMPLES
> +Start a server listening on port 10809 that exposes only the
> +guest-visible contents of a qcow2 file, with no TLS encryption, and
> +with the default export name (an empty string). The command will block
> +until the first successful client disconnects:

TBH I'd always include the -t option in every example.  I don't
understand (except for backwards compatibility) why it isn't the
default since it's something I always trip over when using qemu-nbd.

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