[Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command

[Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command

[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 <programmingkidx@gmail.com>
---
 qemu-img-cmds.hx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
index 69758fb6e8..92f7437944 100644
--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -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
-- 
2.14.3 (Apple Git-98)

Re: [Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command

[Eric Blake]

On 07/30/2018 09:52 PM, John Arbuckle wrote:
> 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 <programmingkidx@gmail.com>
> ---
>   qemu-img-cmds.hx | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
> index 69758fb6e8..92f7437944 100644
> --- a/qemu-img-cmds.hx
> +++ b/qemu-img-cmds.hx
> @@ -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'.


>   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
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

Re: [Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command

[Kevin Wolf]

Am 31.07.2018 um 13:57 hat Eric Blake geschrieben:
> On 07/30/2018 09:52 PM, John Arbuckle wrote:
> > 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 <programmingkidx@gmail.com>
> > ---
> >   qemu-img-cmds.hx | 2 +-
> >   1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
> > index 69758fb6e8..92f7437944 100644
> > --- a/qemu-img-cmds.hx
> > +++ b/qemu-img-cmds.hx
> > @@ -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'.

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

Re: [Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command

[Programmingkid]

> On Jul 31, 2018, at 8:35 AM, Kevin Wolf <kwolf@redhat.com> wrote:
> 
> Am 31.07.2018 um 13:57 hat Eric Blake geschrieben:
>> On 07/30/2018 09:52 PM, John Arbuckle wrote:
>>> 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 <programmingkidx@gmail.com>
>>> ---
>>>  qemu-img-cmds.hx | 2 +-
>>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>> 
>>> diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
>>> index 69758fb6e8..92f7437944 100644
>>> --- a/qemu-img-cmds.hx
>>> +++ b/qemu-img-cmds.hx
>>> @@ -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'.
> 
> 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.

> 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. 

Re: [Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command

[Programmingkid]

> On Jul 31, 2018, at 7:57 AM, Eric Blake <eblake@redhat.com> wrote:
> 
> On 07/30/2018 09:52 PM, John Arbuckle wrote:
>> 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 <programmingkidx@gmail.com>
>> ---
>>  qemu-img-cmds.hx | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>> diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
>> index 69758fb6e8..92f7437944 100644
>> --- a/qemu-img-cmds.hx
>> +++ b/qemu-img-cmds.hx
>> @@ -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.

> 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

> 
>>  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
> 
> -- 
> Eric Blake, Principal Software Engineer
> Red Hat, Inc.           +1-919-301-3266
> Virtualization:  qemu.org | libvirt.org