Clean up the formatting to make the output a bit more readable at least with respect to not having one paragraph of output. Each option will start on its own line. Signed-off-by: John Ferlan <jferlan(a)redhat.com&gt; --- tools/virsh.pod | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 82de2cc45..52f45d721 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -3948,10 +3948,13 @@ before the event. =item B<vol-create> I<pool-or-uuid> I<FILE> [I<--prealloc-metadata>] Create a volume from an XML <file>. + I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in. + I<FILE> is the XML <file> with the volume definition. An easy way to create the XML <file> is to use the B<vol-dumpxml> command to obtain the definition of a pre-existing volume. + [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't support full allocation). This option creates a sparse image file with metadata, resulting in higher performance compared to images with no preallocation and @@ -3963,53 +3966,66 @@ B<Example> vi newvolume.xml (or make changes with your other text editor) virsh vol-create differentstoragepool newvolume.xml -=item B<vol-create-from> I<pool-or-uuid> I<FILE> [I<--inputpool> -I<pool-or-uuid>] I<vol-name-or-key-or-path> [I<--prealloc-metadata>] -[I<--reflink>] +=item B<vol-create-from> I<pool-or-uuid> I<FILE> I<vol-name-or-key-or-path> +[I<--inputpool> I<pool-or-uuid>] [I<--prealloc-metadata>] [I<--reflink>] Create a volume, using another volume as input. + I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in. + I<FILE> is the XML <file> with the volume definition. + +I<vol-name-or-key-or-path> is the name or key or path of the source volume. + I<--inputpool> I<pool-or-uuid> is the name or uuid of the storage pool the source volume is in. -I<vol-name-or-key-or-path> is the name or key or path of the source volume. + [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't support full allocation). This option creates a sparse image file with metadata, resulting in higher performance compared to images with no preallocation and only slightly higher initial disk space usage. + When I<--reflink> is specified, perform a COW lightweight copy, where the data blocks are copied only when modified. If this is not possible, the copy fails. =item B<vol-create-as> I<pool-or-uuid> I<name> I<capacity> -[I<--allocation> I<size>] [I<--format> I<string>] [I<--backing-vol> -I<vol-name-or-key-or-path>] [I<--backing-vol-format> I<string>] -[I<--prealloc-metadata>] [I<--print-xml>] +[I<--allocation> I<size>] [I<--format> I<string>] +[I<--backing-vol> I<vol-name-or-key-or-path>] +[I<--backing-vol-format> I<string>] [I<--prealloc-metadata>] [I<--print-xml>] Create a volume from a set of arguments unless I<--print-xml> is specified, in which case just the XML of the volume object is printed out without any actual object creation. + I<pool-or-uuid> is the name or UUID of the storage pool to create the volume in. + I<name> is the name of the new volume. For a disk pool, this must match the partition name as determined from the pool's source device path and the next available partition. For example, a source device path of /dev/sdb and there are no partitions on the disk, then the name must be sdb1 with the next name being sdb2 and so on. + I<capacity> is the size of the volume to be created, as a scaled integer (see B<NOTES> above), defaulting to bytes if there is no suffix. + I<--allocation> I<size> is the initial size to be allocated in the volume, also as a scaled integer defaulting to bytes. + I<--format> I<string> is used in file based storage pools to specify the volume file format to use; raw, bochs, qcow, qcow2, vmdk, qed. Use extended for disk storage pools in order to create an extended partition (other values are validity checked but not preserved when libvirtd is restarted or the pool is refreshed). + I<--backing-vol> I<vol-name-or-key-or-path> is the source backing volume to be used if taking a snapshot of an existing volume. + I<--backing-vol-format> I<string> is the format of the snapshot backing volume; raw, bochs, qcow, qcow2, qed, vmdk, host_device. These are, however, meant for file based storage pools. + [I<--prealloc-metadata>] preallocate metadata (for qcow2 images which don't support full allocation). This option creates a sparse image file with metadata, resulting in higher performance compared to images with no preallocation and -- 2.13.6

The proper command order is 'virsh vol-delete volume pool'. While making the modification clean up the description a bit too in order to help clarify under what circumstances the volume could be found if the pool name was not provided. Signed-off-by: John Ferlan <jferlan(a)redhat.com&gt; --- tools/virsh.pod | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index ff3b0729e..2d4416b44 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4056,13 +4056,18 @@ When I<--reflink> is specified, perform a COW lightweight copy, where the data blocks are copied only when modified. If this is not possible, the copy fails. -=item B<vol-delete> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path> +=item B<vol-delete> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>] [I<--delete-snapshots>] Delete a given volume. -I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. -I<vol-name-or-key-or-path> is the name or key or path of the volume to delete. + +I<vol-name-or-key-or-path> is the volume name or key or path of the volume +to delete. + +[I<--pool> I<pool-or-uuid>] is the name or UUID of the storage pool the volume +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be deleted; otherwise, +the first volume found by the key or path will be used. The I<--delete-snapshots> flag specifies that any snapshots associated with the storage volume should be deleted as well. Not all storage drivers -- 2.13.6

The proper command order is 'virsh vol-download volume file pool'. While making the modification clean up the description a bit too in order to help clarify under what circumstances the volume could be found if the pool name was not provided. Signed-off-by: John Ferlan <jferlan(a)redhat.com&gt; --- tools/virsh.pod | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index db871db9e..d8cc64f36 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4103,19 +4103,28 @@ See the description for the libvirt virStorageVolUpload API for details regarding possible target volume and pool changes as a result of the pool refresh when the upload is attempted. -=item B<vol-download> [I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>] -[I<--length> I<bytes>] [I<--sparse>] I<vol-name-or-key-or-path> I<local-file> +=item B<vol-download> I<vol-name-or-key-or-path> I<local-file> +[I<--pool> I<pool-or-uuid>] [I<--offset> I<bytes>] [I<--length> I<bytes>] +[I<--sparse>] Download the contents of a storage volume to I<local-file>. + +I<vol-name-or-key-or-path> is the name or key or path of the volume to +download into I<local-file>. + I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. -I<vol-name-or-key-or-path> is the name or key or path of the volume to download. -If I<--sparse> is specified, this command will preserve volume sparseness. +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + I<--offset> is the position in the storage volume at which to start reading -the data. The value must be 0 or larger. I<--length> is an upper bound of -the amount of data to be downloaded. A negative value is interpreted as -an unsigned long long value to essentially include everything from the -offset to the end of the volume. +the data. The value must be 0 or larger. + +I<--length> is an upper bound of the amount of data to be downloaded. +A negative value is interpreted as an unsigned long long value to +essentially include everything from the offset to the end of the volume. + +If I<--sparse> is specified, this command will preserve volume sparseness. =item B<vol-wipe> [I<--pool> I<pool-or-uuid>] [I<--algorithm> I<algorithm>] I<vol-name-or-key-or-path> -- 2.13.6

The proper command order is 'virsh vol-dumpxml volume pool'. While making the modification clean up the description a bit too in order to help clarify under what circumstances the volume could be found if the pool name was not provided. Signed-off-by: John Ferlan <jferlan(a)redhat.com&gt; --- tools/virsh.pod | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 24177e407..135cce841 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4178,12 +4178,17 @@ it expects the storage driver to be able to discard all bytes in a volume. It is up to the storage driver to handle how the discarding occurs. Not all storage drivers or volume types can support 'trim'. -=item B<vol-dumpxml> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path> +=item B<vol-dumpxml> I<vol-name-or-key-or-path> [I<--pool> I<pool-or-uuid>] Output the volume information as an XML dump to stdout. + +I<vol-name-or-key-or-path> is the name or key or path of the volume +to output the XML. + I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. I<vol-name-or-key-or-path> is the name or key or path of the volume -to output the XML of. +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. =item B<vol-info> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key-or-path> [I<--bytes>] [I<--physical>] -- 2.13.6

Make the output more readable. Signed-off-by: John Ferlan <jferlan(a)redhat.com&gt; --- tools/virsh.pod | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index cd1ccc6fa..1b59251bf 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4215,16 +4215,21 @@ have different physical and allocation values. =item B<vol-list> [I<--pool> I<pool-or-uuid>] [I<--details>] Return the list of volumes in the given storage pool. + I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool. + The I<--details> option instructs virsh to additionally display volume type and capacity related information where available. -=item B<vol-pool> [I<--uuid>] I<vol-key-or-path> +=item B<vol-pool> I<vol-key-or-path> [I<--uuid>] Return the pool name or UUID for a given volume. By default, the pool name is -returned. If the I<--uuid> option is given, the pool UUID is returned instead. +returned. + I<vol-key-or-path> is the key or path of the volume to return the pool -information for. +information. + +If the I<--uuid> option is given, the pool UUID is returned instead. =item B<vol-path> [I<--pool> I<pool-or-uuid>] I<vol-name-or-key> -- 2.13.6

Instead of appearing as one long paragraph, split the output to list each command option on its own line for better readability. Signed-off-by: John Ferlan <jferlan(a)redhat.com&gt; --- tools/virsh.pod | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 366a628f9..d3ae7bb5d 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -4264,17 +4264,29 @@ the first volume found by the path will be used. [I<--allocate>] [I<--delta>] [I<--shrink>] Resize the capacity of the given volume, in bytes. + +I<vol-name-or-key-or-path> is the name or key or path of the volume +to resize. + +I<capacity> is a scaled integer (see B<NOTES> above) for the volume, +which defaults to bytes if there is no suffix. + I<--pool> I<pool-or-uuid> is the name or UUID of the storage pool the volume -is in. I<vol-name-or-key-or-path> is the name or key or path of the volume -to resize. The new capacity might be sparse unless I<--allocate> is -specified. Normally, I<capacity> is the new size, but if I<--delta> -is present, then it is added to the existing size. Attempts to shrink -the volume will fail unless I<--shrink> is present; I<capacity> cannot -be negative unless I<--shrink> is provided, but a negative sign is not -necessary. I<capacity> is a scaled integer (see B<NOTES> above), which -defaults to bytes if there is no suffix. This command is only safe -for storage volumes not in use by an active guest; see also -B<blockresize> for live resizing. +is in. If the volume name is provided instead of the key or path, then +providing the pool is necessary to find the volume to be uploaded into; +otherwise, the first volume found by the key or path will be used. + +The new I<capacity> might be sparse unless I<--allocate> is specified. + +Normally, I<capacity> is the new size, but if I<--delta> +is present, then it is added to the existing size. + +Attempts to shrink the volume will fail unless I<--shrink> is present. +The I<capacity> cannot be negative unless I<--shrink> is provided, but +a negative sign is not necessary. + +This command is only safe for storage volumes not in use by an active +guest; see also B<blockresize> for live resizing. =back -- 2.13.6