[Qemu-devel] [PATCH] qemu-img.c: Add examples section

[Qemu-devel] [PATCH] qemu-img.c: Add examples section

[John Arbuckle]

Add an examples section to the help output.

Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
---
 qemu-img.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/qemu-img.c b/qemu-img.c
index 1acddf693c..f77c82695d 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
 
     printf("%s\nSupported formats:", help_msg);
     bdrv_iterate_format(format_print, NULL);
+
+    printf("\n\nExamples:\n\n"
+           "Create: qemu-img create -f qcow2 image.qcow2 10G\n\n"
+           "Info: qemu-img info image.qcow2\n\n"
+           "Resize: qemu-img resize image.qcow2 20G\n\n"
+           "Convert: qemu-img convert -f raw -O qcow2 image.img image.qcow2\n\n"
+           "Check: qemu-img check image.qcow2\n\n"
+           "Map: qemu-img map -f qcow2 --output=human image.qcow2\n\n"
+           "Rebase: qemu-img rebase -b new_backing_file.qcow2 image.qcow2"
+           );
+
     printf("\n\n" QEMU_HELP_BOTTOM "\n");
     exit(EXIT_SUCCESS);
 }
-- 
2.14.3 (Apple Git-98)

Re: [Qemu-devel] [PATCH] qemu-img.c: Add examples section

[Fam Zheng]

On Thu, 08/02 20:50, John Arbuckle wrote:
> Add an examples section to the help output.
> 
> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
> ---
>  qemu-img.c | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/qemu-img.c b/qemu-img.c
> index 1acddf693c..f77c82695d 100644
> --- a/qemu-img.c
> +++ b/qemu-img.c
> @@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
>  
>      printf("%s\nSupported formats:", help_msg);
>      bdrv_iterate_format(format_print, NULL);
> +
> +    printf("\n\nExamples:\n\n"
> +           "Create: qemu-img create -f qcow2 image.qcow2 10G\n\n"
> +           "Info: qemu-img info image.qcow2\n\n"
> +           "Resize: qemu-img resize image.qcow2 20G\n\n"
> +           "Convert: qemu-img convert -f raw -O qcow2 image.img image.qcow2\n\n"
> +           "Check: qemu-img check image.qcow2\n\n"
> +           "Map: qemu-img map -f qcow2 --output=human image.qcow2\n\n"
> +           "Rebase: qemu-img rebase -b new_backing_file.qcow2 image.qcow2"
> +           );

The text looks good but maybe it's better to condense the section by using only
one \n between command lines instead of two?

Fam

> +
>      printf("\n\n" QEMU_HELP_BOTTOM "\n");
>      exit(EXIT_SUCCESS);
>  }
> -- 
> 2.14.3 (Apple Git-98)
> 
> 

Re: [Qemu-devel] [PATCH] qemu-img.c: Add examples section

[Programmingkid]

> On Aug 2, 2018, at 10:10 PM, Fam Zheng <famz@redhat.com> wrote:
> 
> On Thu, 08/02 20:50, John Arbuckle wrote:
>> Add an examples section to the help output.
>> 
>> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
>> ---
>> qemu-img.c | 11 +++++++++++
>> 1 file changed, 11 insertions(+)
>> 
>> diff --git a/qemu-img.c b/qemu-img.c
>> index 1acddf693c..f77c82695d 100644
>> --- a/qemu-img.c
>> +++ b/qemu-img.c
>> @@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
>> 
>>     printf("%s\nSupported formats:", help_msg);
>>     bdrv_iterate_format(format_print, NULL);
>> +
>> +    printf("\n\nExamples:\n\n"
>> +           "Create: qemu-img create -f qcow2 image.qcow2 10G\n\n"
>> +           "Info: qemu-img info image.qcow2\n\n"
>> +           "Resize: qemu-img resize image.qcow2 20G\n\n"
>> +           "Convert: qemu-img convert -f raw -O qcow2 image.img image.qcow2\n\n"
>> +           "Check: qemu-img check image.qcow2\n\n"
>> +           "Map: qemu-img map -f qcow2 --output=human image.qcow2\n\n"
>> +           "Rebase: qemu-img rebase -b new_backing_file.qcow2 image.qcow2"
>> +           );
> 
> The text looks good but maybe it's better to condense the section by using only
> one \n between command lines instead of two?
> 
> Fam

It would be harder on the user's eyes if I did that.

Thank you for reviewing my patch.

Re: [Qemu-devel] [PATCH] qemu-img.c: Add examples section

[Fam Zheng]

On Thu, 08/02 22:34, Programmingkid wrote:
> 
> > On Aug 2, 2018, at 10:10 PM, Fam Zheng <famz@redhat.com> wrote:
> > 
> > On Thu, 08/02 20:50, John Arbuckle wrote:
> >> Add an examples section to the help output.
> >> 
> >> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
> >> ---
> >> qemu-img.c | 11 +++++++++++
> >> 1 file changed, 11 insertions(+)
> >> 
> >> diff --git a/qemu-img.c b/qemu-img.c
> >> index 1acddf693c..f77c82695d 100644
> >> --- a/qemu-img.c
> >> +++ b/qemu-img.c
> >> @@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
> >> 
> >>     printf("%s\nSupported formats:", help_msg);
> >>     bdrv_iterate_format(format_print, NULL);
> >> +
> >> +    printf("\n\nExamples:\n\n"
> >> +           "Create: qemu-img create -f qcow2 image.qcow2 10G\n\n"
> >> +           "Info: qemu-img info image.qcow2\n\n"
> >> +           "Resize: qemu-img resize image.qcow2 20G\n\n"
> >> +           "Convert: qemu-img convert -f raw -O qcow2 image.img image.qcow2\n\n"
> >> +           "Check: qemu-img check image.qcow2\n\n"
> >> +           "Map: qemu-img map -f qcow2 --output=human image.qcow2\n\n"
> >> +           "Rebase: qemu-img rebase -b new_backing_file.qcow2 image.qcow2"
> >> +           );
> > 
> > The text looks good but maybe it's better to condense the section by using only
> > one \n between command lines instead of two?
> > 
> > Fam
> 
> It would be harder on the user's eyes if I did that.

This is objective, but being compact is more consistent in density with the
above "Command syntax" section in this function.

Fam

Re: [Qemu-devel] [PATCH] qemu-img.c: Add examples section

[Programmingkid]

> On Aug 3, 2018, at 4:46 AM, Fam Zheng <famz@redhat.com> wrote:
> 
> On Thu, 08/02 22:34, Programmingkid wrote:
>> 
>>> On Aug 2, 2018, at 10:10 PM, Fam Zheng <famz@redhat.com> wrote:
>>> 
>>> On Thu, 08/02 20:50, John Arbuckle wrote:
>>>> Add an examples section to the help output.
>>>> 
>>>> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
>>>> ---
>>>> qemu-img.c | 11 +++++++++++
>>>> 1 file changed, 11 insertions(+)
>>>> 
>>>> diff --git a/qemu-img.c b/qemu-img.c
>>>> index 1acddf693c..f77c82695d 100644
>>>> --- a/qemu-img.c
>>>> +++ b/qemu-img.c
>>>> @@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
>>>> 
>>>>    printf("%s\nSupported formats:", help_msg);
>>>>    bdrv_iterate_format(format_print, NULL);
>>>> +
>>>> +    printf("\n\nExamples:\n\n"
>>>> +           "Create: qemu-img create -f qcow2 image.qcow2 10G\n\n"
>>>> +           "Info: qemu-img info image.qcow2\n\n"
>>>> +           "Resize: qemu-img resize image.qcow2 20G\n\n"
>>>> +           "Convert: qemu-img convert -f raw -O qcow2 image.img image.qcow2\n\n"
>>>> +           "Check: qemu-img check image.qcow2\n\n"
>>>> +           "Map: qemu-img map -f qcow2 --output=human image.qcow2\n\n"
>>>> +           "Rebase: qemu-img rebase -b new_backing_file.qcow2 image.qcow2"
>>>> +           );
>>> 
>>> The text looks good but maybe it's better to condense the section by using only
>>> one \n between command lines instead of two?
>>> 
>>> Fam
>> 
>> It would be harder on the user's eyes if I did that.
> 
> This is objective, but being compact is more consistent in density with the
> above "Command syntax" section in this function.

I want to break away from that very dense format. It was just too hard to read.

Re: [Qemu-devel] [PATCH] qemu-img.c: Add examples section

[Max Reitz]

[-- Attachment #1: Type: text/plain, Size: 1612 bytes --]

On 2018-08-03 02:50, John Arbuckle wrote:
> Add an examples section to the help output.
> 
> Signed-off-by: John Arbuckle <programmingkidx@gmail.com>
> ---
>  qemu-img.c | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/qemu-img.c b/qemu-img.c
> index 1acddf693c..f77c82695d 100644
> --- a/qemu-img.c
> +++ b/qemu-img.c
> @@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
>  
>      printf("%s\nSupported formats:", help_msg);
>      bdrv_iterate_format(format_print, NULL);
> +
> +    printf("\n\nExamples:\n\n"
> +           "Create: qemu-img create -f qcow2 image.qcow2 10G\n\n"
> +           "Info: qemu-img info image.qcow2\n\n"
> +           "Resize: qemu-img resize image.qcow2 20G\n\n"
> +           "Convert: qemu-img convert -f raw -O qcow2 image.img image.qcow2\n\n"
> +           "Check: qemu-img check image.qcow2\n\n"
> +           "Map: qemu-img map -f qcow2 --output=human image.qcow2\n\n"
> +           "Rebase: qemu-img rebase -b new_backing_file.qcow2 image.qcow2"
> +           );
> +

The examples look good!

I have to agree with Fam, though, that since all the rest of the help
text is rather dense, this should be condensed as well.  I would vote
for replacing all \n\n" by \n" and indenting the example lines by two
spaces.

(I personally am a fan of not-so-dense info, but then again, this is a
--help text, so there is a point in making it dense.)

Also, I think it would be better to order the examples alphabetically.

Max

>      printf("\n\n" QEMU_HELP_BOTTOM "\n");
>      exit(EXIT_SUCCESS);
>  }
> 



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]