| Message ID | 20180803005015.5116-1-programmingkidx@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | qemu-img.c: Add examples section | expand |
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) > >
> 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.
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
> 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.
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); > } >
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); }
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(+)