qemu-img-cmds.hx: Add example usage for create command
PATCH 1/1 qemu-img-cmds.hx: Add example usage for create command
Add an example on how to use the create command. I believe this will make qemu-img easier to use.
--- qemu-img-cmds.hx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
qemu-img-cmds.hx +1 -1
@@ -50,7 +50,7 @@ STEXI ETEXI DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]") + "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]\nExample: qemu-img create -f qcow2 WindowsXP.qcow2 10G") STEXI @item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}] ETEXI
Signature · 1 line
2.14.3 (Apple Git-98)
Quoted 12 lines · John Arbuckle
Add an example on how to use the create command. I believe this will make qemu-img easier to use.
Signed-off-by John Arbuckle <[email protected]>--- qemu-img-cmds.hx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qemu-img-cmds.hx +0
-0
qemu-img-cmds.hx STEXI · line 53
Quoted 5 lines
qemu-img-cmds.hx +1
-1@@ -50,7 +50,7 @@ STEXI ETEXI DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]") + "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]\nExample: qemu-img create -f qcow2 WindowsXP.qcow2 10G")
Making a long line longer. It would be worth using C string concatenation and splitting this over two lines, at the \n.
Using the name WindowsXP.qcow2 as the guest is somewhat misleading (that OS is proprietary, and quickly reaching the point of obsolescence from its vendor - furthermore, qemu-img doesn't actually install an OS, but rather creates a blank image for a later install process to utilize); better would be a generic name that won't go out of date, such 'image.qcow2'.
Quoted 4 lines
qemu-img-cmds.hx +0
-0STEXI @item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}] ETEXI
Signature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org
Am 31.07.2018 um 13:57 hat Eric Blake geschrieben:
Quoted 21 lines · John Arbuckle
Quoted 12 lines
Add an example on how to use the create command. I believe this will make qemu-img easier to use.
Signed-off-by John Arbuckle <[email protected]>--- qemu-img-cmds.hx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qemu-img-cmds.hx +0
-0qemu-img-cmds.hx STEXI · line 52
Quoted 4 lines
qemu-img-cmds.hx +1
-1@@ -50,7 +50,7 @@ STEXI ETEXI DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]") + "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]\nExample: qemu-img create -f qcow2 WindowsXP.qcow2 10G")Making a long line longer. It would be worth using C string concatenation and splitting this over two lines, at the \n.
Quoted 5 lines
Using the name WindowsXP.qcow2 as the guest is somewhat misleading (that OS is proprietary, and quickly reaching the point of obsolescence from its vendor - furthermore, qemu-img doesn't actually install an OS, but rather creates a blank image for a later install process to utilize); better would be a generic name that won't go out of date, such 'image.qcow2'.
Also, while I like the idea of adding examples to the man page, I don't think adding it here would give the right result. The example would appear in the middle of the subcommand syntax lines.
I'd rather add a whole new section "EXAMPLES" in the man page.
Kevin
Quoted 31 lines · Kevin Wolf
Am 31.07.2018 um 13:57 hat Eric Blake geschrieben:
Quoted 21 lines · John Arbuckle
Quoted 12 lines
Add an example on how to use the create command. I believe this will make qemu-img easier to use.
Signed-off-by John Arbuckle <[email protected]>--- qemu-img-cmds.hx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qemu-img-cmds.hx +0
-0qemu-img-cmds.hx STEXI · line 52
Quoted 4 lines
qemu-img-cmds.hx +1
-1@@ -50,7 +50,7 @@ STEXI ETEXI DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]") + "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]\nExample: qemu-img create -f qcow2 WindowsXP.qcow2 10G")Making a long line longer. It would be worth using C string concatenation and splitting this over two lines, at the \n.
Quoted 5 lines
Using the name WindowsXP.qcow2 as the guest is somewhat misleading (that OS is proprietary, and quickly reaching the point of obsolescence from its vendor - furthermore, qemu-img doesn't actually install an OS, but rather creates a blank image for a later install process to utilize); better would be a generic name that won't go out of date, such 'image.qcow2'.
Quoted 3 lines
Also, while I like the idea of adding examples to the man page, I don't think adding it here would give the right result. The example would appear in the middle of the subcommand syntax lines.
As it reads now I don't feel its easy for the user to decipher. Having an example near by would help the user understand how to use it.
Quoted 1 line
I'd rather add a whole new section "EXAMPLES" in the man page.
That is a good idea. I would like to have examples in both documents.
Quoted 20 lines · Eric Blake
Quoted 10 lines · John Arbuckle
Add an example on how to use the create command. I believe this will make qemu-img easier to use.
Signed-off-by John Arbuckle <[email protected]>--- qemu-img-cmds.hx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qemu-img-cmds.hx +0
-0qemu-img-cmds.hx STEXI · line 52
Quoted 4 lines
qemu-img-cmds.hx +1
-1@@ -50,7 +50,7 @@ STEXI ETEXI DEF("create", img_create, - "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]") + "create [--object objectdef] [-q] [-f fmt] [-b backing_file] [-F backing_fmt] [-u] [-o options] filename [size]\nExample: qemu-img create -f qcow2 WindowsXP.qcow2 10G")Making a long line longer. It would be worth using C string concatenation and splitting this over two lines, at the \n.
Sounds like a good idea.
Quoted 1 line
Using the name WindowsXP.qcow2 as the guest is somewhat misleading (that OS is proprietary, and quickly reaching the point of obsolescence from its vendor - furthermore, qemu-img doesn't actually install an OS, but rather creates a blank image for a later install process to utilize); better would be a generic name that won't go out of date, such 'image.qcow2'.
I always felt a concrete example was easier to understand rather than a generic example. What about this:
Example: qemu-img create -f qcow2 <HD image name>.qcow2 10G
Quoted 9 lines
Quoted 4 lines
qemu-img-cmds.hx +0
-0STEXI @item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}] ETEXISignature · 3 lines
Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3266 Virtualization: qemu.org | libvirt.org