[2/2] qemu-nbd: Minor texi updates

- Change some spacing.
- Remove duplicate entry for --format.
- Reword --discard documentation.
- Add --detect-zeroes documentation.

Signed-off-by: Sitsofe Wheeler <sitsofe@yahoo.com>
---
 qemu-nbd.texi | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

On 12/30/2015 12:57 PM, Sitsofe Wheeler wrote:
> - Change some spacing.
> - Remove duplicate entry for --format.
> - Reword --discard documentation.
> - Add --detect-zeroes documentation.
> 
> Signed-off-by: Sitsofe Wheeler <sitsofe@yahoo.com>
> ---
>  qemu-nbd.texi | 22 ++++++++++++++--------
>  1 file changed, 14 insertions(+), 8 deletions(-)
> 

> @@ -22,8 +22,9 @@ offset into the image
>  interface to bind to (default @samp{0.0.0.0})
>  @item -k, --socket=@var{path}
>  Use a unix socket with path @var{path}
> -@item -f, --format=@var{format}
> -Set image format as @var{format}
> +@item -f, --format=@var{fmt}
> +force the use of the block driver for format @var{fmt} instead of
> +auto-detecting

Why are you abbreviating 'format' to 'fmt'? Oh, because that's how the
other duplicate one was worded.

Should probably start with 'Force', to match the capitalization used
earlier....

>  @item -r, --read-only
>  export read-only
>  @item -P, --partition=@var{num}
> @@ -44,17 +45,22 @@ the emulator's @code{-drive cache=...} option for allowed values.
>  choose asynchronous I/O mode between @samp{threads} (the default)
>  and @samp{native} (Linux only).
>  @item --discard=@var{discard}
> -toggles whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})

...then again, later lines are not starting with upper case. Maybe
that's worth its own patch to make it uniformly consistent?

> -requests are ignored or passed to the filesystem.  The default is no
> -(@samp{--discard=ignore}).
> +controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})
> +requests are ignored or passed to the filesystem.  @var{discard} is one of
> +@samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}).  The default is
> +@samp{ignore}.
> +@item --detect-zeroes=@var{detect-zeroes}
> +enables the automatic conversion of plain zero writes by the OS to driver
> +specific optimized zero write commands.  @var{detect-zeroes} is one of

I'd probably write this one as 'driver-specific'

> +@samp{off}, @samp{on} or @samp{unmap}.  @samp{unmap}
> +converts a zero write to an unmap operation and can only be used if
> +@var{discard} is set to @samp{unmap}.  The default is @samp{off}.
>  @item -c, --connect=@var{dev}
>  connect @var{filename} to NBD device @var{dev}
>  @item -d, --disconnect
>  disconnect the specified device
>  @item -e, --shared=@var{num}
>  device can be shared by @var{num} clients (default @samp{1})
> -@item -f, --format=@var{fmt}
> -force block driver for format @var{fmt} instead of auto-detecting
>  @item -t, --persistent
>  don't exit on the last connection
>  @item -v, --verbose
>

On Mon, Jan 04, 2016 at 11:16:03AM -0700, Eric Blake wrote:
> On 12/30/2015 12:57 PM, Sitsofe Wheeler wrote:
> > +@item -f, --format=@var{fmt}
> > +force the use of the block driver for format @var{fmt} instead of
> > +auto-detecting
> 
> Why are you abbreviating 'format' to 'fmt'? Oh, because that's how the
> other duplicate one was worded.

The problem is who to be consistent with? There are a few choices:
o qemu(1)
o qemu --help
o qemu-img(1)
o qemu-img --help
o qemu-nbd --help
o (For NBD options) nbd-server(1)

In the end I decided to try and avoid changing what was already there.

> Should probably start with 'Force', to match the capitalization used
> earlier....
> 
> >  @item -r, --read-only
> >  export read-only
> >  @item -P, --partition=@var{num}
> > @@ -44,17 +45,22 @@ the emulator's @code{-drive cache=...} option for allowed values.
> >  choose asynchronous I/O mode between @samp{threads} (the default)
> >  and @samp{native} (Linux only).
> >  @item --discard=@var{discard}
> > -toggles whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})
> 
> ...then again, later lines are not starting with upper case. Maybe
> that's worth its own patch to make it uniformly consistent?

OK I've posted an updated patch set with the capitalisation fixed as
another patch.

> > +@item --detect-zeroes=@var{detect-zeroes}
> > +enables the automatic conversion of plain zero writes by the OS to driver
> > +specific optimized zero write commands.  @var{detect-zeroes} is one of
> 
> I'd probably write this one as 'driver-specific'

OK I've changed this in the updated patch set (although this makes
things inconsistent with qemu(1)).