[PATCH 1/3] Improve blockpull man entry

[Peter Krempa]

On Wed, Apr 15, 2020 at 11:34:04 +0000, Sebastian Mitterle wrote:
> 1. Mention usage of `--base` and `--bandwidth` and fix cmd syntax.
> 2. Explain valid arguments for `base`.
> 3. Move explanation for `--keep-relative` to end considering it
>    less frequent use case because libvirt doesn't create relative
>    backing chain names.
> 4. Add reference to documentation for relative paths in backing chains.
> 
> Signed-off-by: Sebastian Mitterle <smitterl at redhat.com>
> ---
>  docs/manpages/virsh.rst | 19 +++++++++++++------
>  1 file changed, 13 insertions(+), 6 deletions(-)
> 
> diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
> index dc404ddfe8..27ecc53d56 100644
> --- a/docs/manpages/virsh.rst
> +++ b/docs/manpages/virsh.rst
> @@ -1345,7 +1345,7 @@ blockpull
>  
>  .. code-block::
>  
> -   blockpull domain path [bandwidth] [--bytes] [base]
> +   blockpull domain path { [bandwidth [--bytes] [base]] | [--bandwidth [--bytes]] [--base] }

For any argument where the '--' can be skipped we use the non-dash
syntax. Additionally your version is missing the argument placeholder.

>        [--wait [--verbose] [--timeout seconds] [--async]]
>        [--keep-relative]
>  
> @@ -1353,7 +1353,7 @@ Populate a disk from its backing image chain. By default, this command
>  flattens the entire chain; but if *base* is specified, containing the
>  name of one of the backing files in the chain, then that file becomes
>  the new backing file and only the intermediate portion of the chain is
> -pulled.  Once all requested data from the backing image chain has been
> +pulled. Once all requested data from the backing image chain has been
>  pulled, the disk no longer depends on that portion of the backing chain.

This is somewhat common in our docs. (two spaces between sentences)

>  
>  By default, this command returns as soon as possible, and data for
> @@ -1367,16 +1367,23 @@ is triggered, *--async* will return control to the user as fast as
>  possible, otherwise the command may continue to block a little while
>  longer until the job is done cleaning up.
>  
> -Using the *--keep-relative* flag will keep the backing chain names
> -relative.
> -
>  *path* specifies fully-qualified path of the disk; it corresponds
>  to a unique target name (<target dev='name'/>) or source file (<source
>  file='name'/>) for one of the disk devices attached to *domain* (see
>  also ``domblklist`` for listing these names).
> +
>  *bandwidth* specifies copying bandwidth limit in MiB/s. For further information
>  on the *bandwidth* argument see the corresponding section for the ``blockjob``
> -command.
> +command. Using *--bytes* flag indicates the value in *bandwidth* is given in
> +bytes.
> +
> +*base* specifies fully-qualified path of the backing file; it corresponds
> +to a unique indexed target name 'name[i]' (<target dev='name'/>..
> +<backingStore index='i'/>) or source file 'name' (<source file='name'/>).

Well, it's either a fully qualified path, or preferrably the 'name[i]'
thing. but 'name[i]' is not a fully qualified path.

> +
> +Using the *--keep-relative* flag will keep the backing chain names
> +relative (details on `https://www.libvirt.org/kbase/backing_chains.html
> +<https://www.libvirt.org/kbase/backing_chains.html>`__).

I don't think this document contains information on relative file paths.