Skip to contentSkip to conversation

qemu-img: fix .hx and .texi disparity

PATCH Applied John Snow 4 participants 6 messages Apr 9, 2019 – Apr 12, 2019

lore
Share & tools
lore

John Snow

author
#0 lore raw

PATCH 1/1 qemu-img: fix .hx and .texi disparity

It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid.

There are three locations:
(1) .hx file, formatted as texi
(2) .hx file, formatted as human readable.
(3) .texi file, as section headers, formatted as texi.

You can compare the two summaries within the .hx file like so:

Human-readable command summaries:
./qemu-img --help | grep 'Command syntax' -A14 Detokenized texi command summaries:
grep "@item" qemu-img-cmds.hx | sed -E 's|@var\{([^\}]*?)\}|\1|g'

You can compare the two separate texi summaries like so:

Texi command summaries:
grep "@item" qemu-img-cmds.hx"
Texi command headers:
grep -E "@item.*@var" qemu-img.texi | tail -14

---
 qemu-img.texi    | 4 ++--
 qemu-img-cmds.hx | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
qemu-img.texi +2 -2
index 3b6710a580..724f244ba1 100644
@@ -197,7 +197,7 @@ Command description:
 
 @table @option
 
-@item amend [--object @var{objectdef}] [--image-opts] [-p] [-p] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
+@item amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
 
 Amends the image format specific @var{options} for the image file
 @var{filename}. Not all file formats support this operation.
@@ -424,7 +424,7 @@ To enumerate information about each disk image in the above chain, starting from
 qemu-img info --backing-chain snap2.qcow2
 @end example
 
-@item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
+@item map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [-U] @var{filename}
 
 Dump the metadata of image @var{filename} and its backing file chain.
 In particular, this commands dumps the allocation state of every sector
qemu-img-cmds.hx +1 -1
index 1526f327a5..4b47f7495d 100644
@@ -46,7 +46,7 @@ ETEXI
 DEF("convert", img_convert,
     "convert [--object objectdef] [--image-opts] [--target-image-opts] [-U] [-C] [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt] [-B backing_file] [-o options] [-l snapshot_param] [-S sparse_size] [-m num_coroutines] [-W] filename [filename2 [...]] output_filename")
 STEXI
-@item convert [--object @var{objectdef}] [--image-opts] [--target-image-opts] [-U] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename}
+@item convert [--object @var{objectdef}] [--image-opts] [--target-image-opts] [-U] [-C] [-c] [-p] [-q] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename}
 ETEXI
 
 DEF("create", img_create,
Signature · 1 line
2.17.2
Reviewed-by on v1 1/1
#1 lore raw
Quoted 16 lines · John Snow

It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid.

There are three locations:
(1) .hx file, formatted as texi
(2) .hx file, formatted as human readable.
(3) .texi file, as section headers, formatted as texi.

You can compare the two summaries within the .hx file like so:

Human-readable command summaries:
./qemu-img --help | grep 'Command syntax' -A14 Detokenized texi command summaries:
grep "@item" qemu-img-cmds.hx | sed -E 's|@var\{([^\}]*?)\}|\1|g'

Quoted 8 lines

You can compare the two separate texi summaries like so:

Texi command summaries:
grep "@item" qemu-img-cmds.hx"
Texi command headers:
grep -E "@item.*@var" qemu-img.texi | tail -14

Extra points for explaining how you found the issues in detail sufficient for reproducing.

Nice to have in 4.0.

author
#2 lore raw
Quoted 25 lines · Markus Armbruster
Quoted 23 lines · John Snow

It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid.

There are three locations:
(1) .hx file, formatted as texi
(2) .hx file, formatted as human readable.
(3) .texi file, as section headers, formatted as texi.

You can compare the two summaries within the .hx file like so:

Human-readable command summaries:
./qemu-img --help | grep 'Command syntax' -A14 Detokenized texi command summaries:
grep "@item" qemu-img-cmds.hx | sed -E 's|@var\{([^\}]*?)\}|\1|g'

You can compare the two separate texi summaries like so:

Texi command summaries:
grep "@item" qemu-img-cmds.hx"
Texi command headers:
grep -E "@item.*@var" qemu-img.texi | tail -14

Quoted 9 lines
Quoted 1 line

Extra points for explaining how you found the issues in detail sufficient for reproducing.

Nice to have in 4.0.

If it can go in for 4.0, who stages it? Kevin?

--js

#3 lore raw
Quoted 11 lines · John Snow
Quoted 8 lines · Markus Armbruster
Quoted 4 lines · John Snow

It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid.

Quoted 6 lines
Quoted 4 lines

Nice to have in 4.0.

If it can go in for 4.0, who stages it? Kevin?

At this point, we've missed -rc3; the fix on its own is not a release-blocker, but if something else comes up that requires -rc4 for an actual release blocker, we can sort out someone sending a pull request for this one at the same time. (I'm aware of a couple of iotest fixups in the same boat... Guess it's time to start updating the wiki to point to email threads where we document 'wish list' patches)

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
author
#4 lore raw
Quoted 17 lines · Eric Blake
Quoted 16 lines · John Snow
Quoted 12 lines · Markus Armbruster
Quoted 4 lines · John Snow

It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid.

Nice to have in 4.0.

Quoted 9 lines
Quoted 1 line

If it can go in for 4.0, who stages it? Kevin?

At this point, we've missed -rc3; the fix on its own is not a release-blocker, but if something else comes up that requires -rc4 for an actual release blocker, we can sort out someone sending a pull request for this one at the same time. (I'm aware of a couple of iotest fixups in the same boat... Guess it's time to start updating the wiki to point to email threads where we document 'wish list' patches)

OK. I also have... a pretty major bitmaps documentation rewrite which I probably won't have ready in time for a theoretical rc4 either, so I guess I'll need to include it for 4.0.1.

I didn't realize how badly out of date the bitmaps.rst file had gotten. I'll keep hammering away at it.

--js

#5 lore raw
In reply to John Snow
Quoted 24 lines · John Snow

It turns out that having options listed in three places continues to be a bad idea. I'm still toying with the idea of an improved infrastructure here, but in the meantime, another bandaid.

There are three locations:
(1) .hx file, formatted as texi
(2) .hx file, formatted as human readable.
(3) .texi file, as section headers, formatted as texi.

You can compare the two summaries within the .hx file like so:

Human-readable command summaries:
./qemu-img --help | grep 'Command syntax' -A14 Detokenized texi command summaries:
grep "@item" qemu-img-cmds.hx | sed -E 's|@var\{([^\}]*?)\}|\1|g'

You can compare the two separate texi summaries like so:

Texi command summaries:
grep "@item" qemu-img-cmds.hx"
Texi command headers:
grep -E "@item.*@var" qemu-img.texi | tail -14

Quoted 5 lines
---
 qemu-img.texi    | 4 ++--
 qemu-img-cmds.hx | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

Applied to master for rc4, since we needed an rc4 anyway and this is a safe docs change.

thanks
-- PMM