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

[Eric Blake <eblake@redhat.com>]

On 12/15/18 8:13 AM, Richard W.M. Jones wrote:
> 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.

Seems reasonable.

> 
>> +@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.

I'd still like one example without -t, to call out specifically that it 
creates a one-shot server that goes away after the first client, but 
don't mind fixing the rest of the examples to use -t.

Using -e for read-only connections makes sense, using -e for writable 
exports is a bit more questionable - we _don't_ advertise the 
NBD_FLAG_CAN_MULTI_CONN which states that caches are kept consistent 
between simultaneous write connections, although maybe we should see if 
qemu-nbd can start promising multi-write consistency in future patches?

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org