[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create
From: |
Programmingkid |
Subject: |
Re: [Qemu-devel] [PATCH] qemu-img-cmds.hx: Add example usage for create command |
Date: |
Tue, 31 Jul 2018 09:14:47 -0400 |
> On Jul 31, 2018, at 8:35 AM, Kevin Wolf <address@hidden> 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 <address@hidden>
>>> ---
>>> 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.