[PATCH 0/3] doc: minor improvements
Minor man/doc improvements related to blockpull. Sebastian Mitterle (3): Improve blockpull man entry Improve Disk image chains documentation Add version info on domaincaps doc docs/formatdomaincaps.html.in | 3 ++- docs/kbase/backing_chains.rst | 36 +++++++++++++++++------------------ docs/manpages/virsh.rst | 19 ++++++++++++------ 3 files changed, 33 insertions(+), 25 deletions(-) -- 2.25.2
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@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] } [--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. 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'/>). + +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>`__). blockresize -- 2.25.2
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@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.
On Fri, Apr 17, 2020 at 14:52:06 +0200, Peter Krempa wrote:
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@redhat.com> --- docs/manpages/virsh.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-)
[...]
+ +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.
It actually does. Unfortunately it doesn't specify how to take a snapshot with relative paths thoug. But this is probably okay then.
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@redhat.com> --- docs/manpages/virsh.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-)
Given new information about the virsh argument parser I've figured out I'll re-review this patch:
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] }
So bandwidth indeed is a positional argument. Since all of the manpage uses the syntax we've had here originally fixing just this place would be wrong. The only fix that should be done here is to group the --bytes flag under bandwidth as specifying --bytes is mandatory.
[--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.
As mentioned previously some of the docs use two spaces between sentences. If it should be fixed then all of it should be fixed in one patch. Please drop this hunk.
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'/>).
I'd move this hunk under the first paragraph in section about blockpull since it explains what 'base' actually is along with some rewording: Something like *base* can eithr be specified as indexed target name 'name[i]' where 'name corresponds to the disk target name (<target dev='name'/>) and 'i' corresponds to the 'index' of the '<backingStore>', or the file name of backing file (<source file='name'/>).
+ +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>`__).
blockresize -- 2.25.2
So bandwidth indeed is a positional argument. Since all of the manpage uses the syntax we've had here originally fixing just this place would be wrong. The only fix that should be done here is to group the --bytes flag under bandwidth as specifying --bytes is mandatory.
I think there's misunderstanding: # virsh blockpull fedora vda vda[1] error: Scaled numeric value 'vda[1]' for <--bandwidth> option is malformed or out of range # virsh blockpull fedora vda 1024 vda[1] Block Pull started I'll change to [bandwidth [--bytes] [base]] On Fri, Apr 24, 2020 at 9:35 AM Peter Krempa <pkrempa@redhat.com> wrote:
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@redhat.com> --- docs/manpages/virsh.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-)
Given new information about the virsh argument parser I've figured out I'll re-review this patch:
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] }
So bandwidth indeed is a positional argument. Since all of the manpage uses the syntax we've had here originally fixing just this place would be wrong. The only fix that should be done here is to group the --bytes flag under bandwidth as specifying --bytes is mandatory.
[--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.
As mentioned previously some of the docs use two spaces between sentences. If it should be fixed then all of it should be fixed in one patch.
Please drop this hunk.
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'/>).
I'd move this hunk under the first paragraph in section about blockpull since it explains what 'base' actually is along with some rewording:
Something like
*base* can eithr be specified as indexed target name 'name[i]' where 'name corresponds to the disk target name (<target dev='name'/>) and 'i' corresponds to the 'index' of the '<backingStore>', or the file name of backing file (<source file='name'/>).
+ +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>`__).
blockresize -- 2.25.2
-- Best, Sebastian
On 4/28/20 9:19 AM, Sebastian Mitterle wrote:
So bandwidth indeed is a positional argument. Since all of the manpage uses the syntax we've had here originally fixing just this place would be wrong. The only fix that should be done here is to group the --bytes flag under bandwidth as specifying --bytes is mandatory.
I think there's misunderstanding:
# virsh blockpull fedora vda vda[1]
We should really encourage users to properly quote their command line to avoid unintentional globbing: # virsh blockpull fedora vda "vda[1]" (Otherwise, if I 'touch vda1', the unquoted command will see the argument 'vda1')
error: Scaled numeric value 'vda[1]' for <--bandwidth> option is malformed or out of range
# virsh blockpull fedora vda 1024 vda[1] Block Pull started
I'll change to [bandwidth [--bytes] [base]]
-- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
We should really encourage users to properly quote their command line to avoid unintentional globbing:
Not sure I understand, is this a request to use '"name[i]"' with single and double quotes in the manpage? Please, note that the line you quote is not part of the patch but sample invocations to demonstrate behavior of blockpull command regarding mandatory positional arguments to justify v2 of this patch. On Tue, Apr 28, 2020 at 4:33 PM Eric Blake <eblake@redhat.com> wrote:
On 4/28/20 9:19 AM, Sebastian Mitterle wrote:
So bandwidth indeed is a positional argument. Since all of the manpage uses the syntax we've had here originally fixing just this place would be wrong. The only fix that should be done here is to group the --bytes flag under bandwidth as specifying --bytes is mandatory.
I think there's misunderstanding:
# virsh blockpull fedora vda vda[1]
We should really encourage users to properly quote their command line to avoid unintentional globbing:
# virsh blockpull fedora vda "vda[1]"
(Otherwise, if I 'touch vda1', the unquoted command will see the argument 'vda1')
error: Scaled numeric value 'vda[1]' for <--bandwidth> option is malformed or out of range
# virsh blockpull fedora vda 1024 vda[1] Block Pull started
I'll change to [bandwidth [--bytes] [base]]
-- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
-- Best, Sebastian
On 4/29/20 8:11 AM, Sebastian Mitterle wrote:
We should really encourage users to properly quote their command line to avoid unintentional globbing:
Not sure I understand, is this a request to use '"name[i]"' with single and double quotes in the manpage?
One or the other, but not both. Buggy: # virsh blockpull fedora vda vda[1] Ok: # virsh blockpull fedora vda 'vda[1]' # virsh blockpull fedora vda "vda[1]" # virsh blockpull fedora vda vda\[1] the point is that any shell example that can misbehave due to globbing if underquoted should instead be properly quoted.
Please, note that the line you quote is not part of the patch but sample invocations to demonstrate behavior of blockpull command regarding mandatory positional arguments to justify v2 of this patch.
If the example is not something you plan on putting in the man page, then that's okay. I was just pointing out that anything mentioned in the man page should also mention the need for proper shell quoting. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
If the example is not something you plan on putting in the man page, then that's okay. I was just pointing out that anything mentioned in the man page should also mention the need for proper shell quoting.
Got it, thank you. I'm unsure. No, I wasn't planning on adding an example. Peter, you initially reviewed this patch, what do you think? (I checked and I don't see many examples on the manpage in general.) Personally, I like examples but am unsure about the scope, like how many examples, which options should be exemplified, etc. On Wed, Apr 29, 2020 at 4:16 PM Eric Blake <eblake@redhat.com> wrote:
On 4/29/20 8:11 AM, Sebastian Mitterle wrote:
We should really encourage users to properly quote their command line to avoid unintentional globbing:
Not sure I understand, is this a request to use '"name[i]"' with single and double quotes in the manpage?
One or the other, but not both.
Buggy: # virsh blockpull fedora vda vda[1]
Ok: # virsh blockpull fedora vda 'vda[1]' # virsh blockpull fedora vda "vda[1]" # virsh blockpull fedora vda vda\[1]
the point is that any shell example that can misbehave due to globbing if underquoted should instead be properly quoted.
Please, note that the line you quote is not part of the patch but sample invocations to demonstrate behavior of blockpull command regarding mandatory positional arguments to justify v2 of this patch.
If the example is not something you plan on putting in the man page, then that's okay. I was just pointing out that anything mentioned in the man page should also mention the need for proper shell quoting.
-- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
-- Best, Sebastian
1. Use 'setup' consistently as noun, 'set up' as verb 2. Use path variables like '$IMAGE_PATH' consistently like in Troubleshooting to improve readability 3. Remove ':' from field names 4. Change phrasing in sentences I stumbled upon several times to improve readability. 5. Minor grammar/vocab fixes. Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/kbase/backing_chains.rst | 36 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst index af848ccb14..c112f2bc82 100644 --- a/docs/kbase/backing_chains.rst +++ b/docs/kbase/backing_chains.rst @@ -38,13 +38,13 @@ image of the backing chain. This configuration will prompt libvirt to detect the backing image of the source image and recursively do the same thing until the end of the chain. -Importance of properly setup backing chain ------------------------------------------- +Importance of proper backing chain setup +---------------------------------------- -The disk image locations are used by libvirt to properly setup the security -system used on the host so that the hypervisor can access the files and possibly -also directly to configure the hypervisor to use the appropriate images. Thus -it's important to properly setup the formats and paths of the backing images. +The disk image locations are used by libvirt to properly set up the security +system used on the host so that the hypervisor can access the files; it can +also be used to configure the hypervisor to use the appropriate images. Thus +it's important to properly set up the formats and paths of the backing images. Any externally created image should always use the -F switch of ``qemu-img`` to specify the format of the backing file to avoid probing. @@ -60,7 +60,7 @@ explicitly in the XML or the overlay image itself. Libvirt also might lack support for a network disk storage technology and thus may be unable to visit and detect backing chains on such storage. This may -result in the backing chain present in the live XML to look incomplete or some +result in the backing chain in the live XML looking incomplete or some operations not being possible. To prevent this it's possible to specify the image metadata explicitly in the XML. @@ -104,7 +104,7 @@ An empty ``<backingStore/>`` element signals the end of the chain. Using this will prevent libvirt or qemu from probing the backing chain. Note that it's also possible to partially specify the chain in the XML but omit -the terminating element. This will result into probing from the last specified +the terminating element. This will result in probing from the last specified ``<backingStore>`` Any image specified explicitly will not be probed for backing file or format. @@ -120,10 +120,10 @@ means that the **-F** parameter of ``qemu-img`` must always be used. :: - qemu-img -f qcow2 -F qcow2 -b /path/to/backing /path/to/overlay + qemu-img -f qcow2 -F qcow2 -b $BACKING_IMAGE_PATH $IMAGE_PATH -Note that if '/path/to/backing' is relative the path is considered relative to -the location of '/path/to/overlay'. +Note that if ``$BACKING_IMAGE_PATH`` is relative the path is considered relative to +the location of ``$IMAGE_PATH``. Troubleshooting =============== @@ -164,7 +164,7 @@ the image has a backing image format specified: refcount bits: 16 corrupt: false -If the ``backing file format:`` field is missing above the format was not +If the ``backing file format`` field is missing above the format was not specified properly. The image can be fixed by the following command: :: @@ -177,22 +177,22 @@ If relative referencing of the backing image is desired, the path must be relative to the location of image described by ``$IMAGE_PATH``. **Important:** If the ``$BACKING_IMAGE_FORMAT`` is not known it can be queried -using ``qemu-img info $BACKING_IMAGE_PATH`` and looking for the ``file format:`` -field, but for security reasons should be used *only* if at least one of the -following criteria is met: +using ``qemu-img info $BACKING_IMAGE_PATH`` and looking for the ``file format`` +field, but for security reasons the value should be used *only* if at least one +of the following criteria is met: - ``file format`` is ``raw`` - ``backing file`` is NOT present - ``backing file`` is present AND is correct/trusted -Note that the last criteria may require manual inspection and thus should not +Note that the last criterion may require manual inspection and thus should not be scripted unless the trust for the image can be expressed programatically. Also note that the above steps may need to be repeated recursively for any subsequent backing images. -Missing images reported after after moving disk images into a different path ----------------------------------------------------------------------------- +Missing images reported after moving disk images into a different path +---------------------------------------------------------------------- The path to the backing image which is recorded in the image metadata often contains a full path to the backing image. This is the default libvirt-created -- 2.25.2
On Wed, Apr 15, 2020 at 11:34:05 +0000, Sebastian Mitterle wrote:
1. Use 'setup' consistently as noun, 'set up' as verb 2. Use path variables like '$IMAGE_PATH' consistently like in Troubleshooting to improve readability 3. Remove ':' from field names 4. Change phrasing in sentences I stumbled upon several times to improve readability. 5. Minor grammar/vocab fixes.
Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/kbase/backing_chains.rst | 36 +++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-)
Reviewed-by: Peter Krempa <pkrempa@redhat.com> I'll push this one in a while.
1. Add 'since 5.10' as commonly used in formatdomain to avoid misunderstandings if element is not present (Is it not supported because of my version or because of my environment?) Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/formatdomaincaps.html.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index 4056e0bd31..70b1d2a8f9 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -561,7 +561,8 @@ <p>Reports whether the hypervisor will obey the <backingStore> elements configured for a <disk> when booting the guest, hotplugging - the disk to a running guest, or similar. + the disk to a running guest, or similar, <span class="since">since 5.10 + </span>. </p> <h4><a id="featureBackup">backup</a></h4> -- 2.25.2
On Wed, Apr 15, 2020 at 11:34:06 +0000, Sebastian Mitterle wrote:
1. Add 'since 5.10' as commonly used in formatdomain to avoid misunderstandings if element is not present (Is it not supported because of my version or because of my environment?)
Signed-off-by: Sebastian Mitterle <smitterl@redhat.com> --- docs/formatdomaincaps.html.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
For some reason we didn't include the since tags here, but it certainly might come in handy.
diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in index 4056e0bd31..70b1d2a8f9 100644 --- a/docs/formatdomaincaps.html.in +++ b/docs/formatdomaincaps.html.in @@ -561,7 +561,8 @@
<p>Reports whether the hypervisor will obey the <backingStore> elements configured for a <disk> when booting the guest, hotplugging - the disk to a running guest, or similar. + the disk to a running guest, or similar, <span class="since">since 5.10 + </span>.
I'll just put the contents of the since tag into brackets after the end of the sentence.
</p>
<h4><a id="featureBackup">backup</a></h4>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
-- 2.25.2
friendly ping On Wed, Apr 15, 2020 at 1:34 PM Sebastian Mitterle <smitterl@redhat.com> wrote:
Minor man/doc improvements related to blockpull.
Sebastian Mitterle (3): Improve blockpull man entry Improve Disk image chains documentation Add version info on domaincaps doc
docs/formatdomaincaps.html.in | 3 ++- docs/kbase/backing_chains.rst | 36 +++++++++++++++++------------------ docs/manpages/virsh.rst | 19 ++++++++++++------ 3 files changed, 33 insertions(+), 25 deletions(-)
-- 2.25.2
-- Best, Sebastian
participants (3)
-
Eric Blake -
Peter Krempa -
Sebastian Mitterle