qemu-img.c: Add examples section

PATCH In review John Arbuckle 3 participants 6 messages Aug 3, 2018 – Aug 13, 2018

lore

Share & tools

lore

John Arbuckle

author

2018-08-03 00:50 UTC #0 lore raw

PATCH 1/1 qemu-img.c: Add examples section

Add an examples section to the help output.

Signed-off-by John Arbuckle <[email protected]>

---
 qemu-img.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

qemu-img.c +11 -0

index 1acddf693c..f77c82695d 100644
@@ -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);
 }

Signature · 1 line

2.14.3 (Apple Git-98)

Fam Zheng

2018-08-03 02:10 UTC #1 lore raw

Quoted 15 lines · John Arbuckle

Add an examples section to the help output.

Signed-off-by John Arbuckle <[email protected]>

---
 qemu-img.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

qemu-img.c +0 -0

index 1acddf693c..f77c82695d 100644
@@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
 
     printf("%s\nSupported formats:", help_msg);
     bdrv_iterate_format(format_print, NULL);

qemu-img.c static void QEMU_NORETURN help(void) · line 211

Quoted 10 lines

qemu-img.c +10 -0

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

Quoted 8 lines

qemu-img.c +1 -0

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

Signature · 1 line

2.14.3 (Apple Git-98)

Programmingkid

author

2018-08-03 02:34 UTC #2 lore raw

Quoted 33 lines · Fam Zheng

Quoted 15 lines · John Arbuckle

Add an examples section to the help output.
Signed-off-by John Arbuckle <[email protected]>
---
qemu-img.c | 11 +++++++++++
1 file changed, 11 insertions(+)
qemu-img.c +0 -0
index 1acddf693c..f77c82695d 100644
@@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
 
    printf("%s\nSupported formats:", help_msg);
    bdrv_iterate_format(format_print, NULL);

qemu-img.c static void QEMU_NORETURN help(void) · line 211

Quoted 10 lines

qemu-img.c +10 -0

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

Quoted 1 line

Fam

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

Thank you for reviewing my patch.

Fam Zheng

2018-08-03 08:46 UTC #3 lore raw

Quoted 33 lines · Programmingkid

Quoted 33 lines · Fam Zheng

Quoted 15 lines · John Arbuckle

Add an examples section to the help output.
Signed-off-by John Arbuckle <[email protected]>
---
qemu-img.c | 11 +++++++++++
1 file changed, 11 insertions(+)
qemu-img.c +0 -0
index 1acddf693c..f77c82695d 100644
@@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
 
    printf("%s\nSupported formats:", help_msg);
    bdrv_iterate_format(format_print, NULL);

qemu-img.c static void QEMU_NORETURN help(void) · line 211

Quoted 10 lines

qemu-img.c +10 -0

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

Quoted 3 lines

Quoted 1 line
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

Programmingkid

author

2018-08-03 12:40 UTC #4 lore raw

Quoted 37 lines · Fam Zheng

Quoted 33 lines · Programmingkid
Quoted 33 lines · Fam Zheng
Quoted 15 lines · John Arbuckle
Add an examples section to the help output.
Signed-off-by John Arbuckle <[email protected]>
---
qemu-img.c | 11 +++++++++++
1 file changed, 11 insertions(+)
qemu-img.c +0 -0
index 1acddf693c..f77c82695d 100644
@@ -199,6 +199,17 @@ static void QEMU_NORETURN help(void)
 
   printf("%s\nSupported formats:", help_msg);
   bdrv_iterate_format(format_print, NULL);
qemu-img.c static void QEMU_NORETURN help(void) · line 211
Quoted 10 lines
qemu-img.c +10 -0
+
+    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?

Quoted 6 lines

Quoted 3 lines
Quoted 1 line
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.

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

Quoted 4 lines

qemu-img.c +0 -0

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