[Qemu-devel] [PATCH 0/5] qemu-img: make subcommand usage docstrings consistent

[Qemu-devel] [PATCH 0/5] qemu-img: make subcommand usage docstrings consistent

[John Snow]

I'm working on a project to attempt to autogenerate all of this, but
until then let's just do a bit of the usual kinds of tidying.

________________________________________________________________________________

For convenience, this branch is available at:
https://github.com/jnsnow/qemu.git branch trivial-qemu-img
https://github.com/jnsnow/qemu/tree/trivial-qemu-img

This version is tagged trivial-qemu-img-v1:
https://github.com/jnsnow/qemu/releases/tag/trivial-qemu-img-v1

John Snow (5):
  qemu-img-commands.hx: argument ordering fixups
  qemu-img.texi: fix command ordering
  qemu-img: remove references to GEN_DOCS
  qemu-img: Make documentation between .texi and .hx consistent
  qemu-img-cmds.hx: add passive-aggressive note

 qemu-img-cmds.hx       | 13 +++++----
 qemu-img.c             |  2 --
 qemu-img.texi          | 78 ++++++++++++++++++++++++++------------------------
 qemu-options-wrapper.h |  1 -
 4 files changed, 48 insertions(+), 46 deletions(-)

-- 
2.14.3

[Qemu-devel] [PATCH 1/5] qemu-img-commands.hx: argument ordering fixups

[John Snow]

The TEXI and string versions are actually identical, except for markup.
We can probably automate this... but make the ordering the same until
then.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qemu-img-cmds.hx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
index 2fe31893cf..8bcefcafe9 100644
--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -23,13 +23,13 @@ STEXI
 ETEXI
 
 DEF("check", img_check,
-    "check [-q] [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
+    "check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
 STEXI
 @item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{filename}
 ETEXI
 
 DEF("commit", img_commit,
-    "commit [-q] [--object objectdef] [--image-opts] [-f fmt] [-t cache] [-b base] [-d] [-p] filename")
+    "commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b base] [-d] [-p] filename")
 STEXI
 @item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
 ETEXI
@@ -47,7 +47,7 @@ STEXI
 ETEXI
 
 DEF("create", img_create,
-    "create [-q] [--object objectdef] [-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]")
 STEXI
 @item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
 ETEXI
-- 
2.14.3

[Qemu-devel] [PATCH 2/5] qemu-img.texi: fix command ordering

[John Snow]

This should match the summary ordering, which is alphabetical.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qemu-img.texi | 58 ++++++++++++++++++++++++++++++----------------------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index 8a26400adb..adf5176902 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -193,6 +193,12 @@ sets the number of input blocks to skip
 Command description:
 
 @table @option
+
+@item amend [-p] [-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.
+
 @item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] @var{filename}
 
 Run a simple sequential I/O benchmark on the specified image. If @code{-w} is
@@ -253,30 +259,6 @@ If @code{-r} is specified, exit codes representing the image state refer to the
 state after (the attempt at) repairing it. That is, a successful @code{-r all}
 will yield the exit code 0, independently of the image state before.
 
-@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
-
-Create the new disk image @var{filename} of size @var{size} and format
-@var{fmt}. Depending on the file format, you can add one or more @var{options}
-that enable additional features of this format.
-
-If the option @var{backing_file} is specified, then the image will record
-only the differences from @var{backing_file}. No size needs to be specified in
-this case. @var{backing_file} will never be modified unless you use the
-@code{commit} monitor command (or qemu-img commit).
-
-If a relative path name is given, the backing file is looked up relative to
-the directory containing @var{filename}.
-
-Note that a given backing file will be opened to check that it is valid. Use
-the @code{-u} option to enable unsafe backing file mode, which means that the
-image will be created even if the associated backing file cannot be opened. A
-matching backing file must be created or additional options be used to make the
-backing file specification valid when you want to use an image created this
-way.
-
-The size can also be specified using the @var{size} option with @code{-o},
-it doesn't need to be specified separately in this case.
-
 @item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
 
 Commit the changes recorded in @var{filename} in its base image or backing file.
@@ -381,6 +363,30 @@ creating compressed images.
 @var{num_coroutines} specifies how many coroutines work in parallel during
 the convert process (defaults to 8).
 
+@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
+
+Create the new disk image @var{filename} of size @var{size} and format
+@var{fmt}. Depending on the file format, you can add one or more @var{options}
+that enable additional features of this format.
+
+If the option @var{backing_file} is specified, then the image will record
+only the differences from @var{backing_file}. No size needs to be specified in
+this case. @var{backing_file} will never be modified unless you use the
+@code{commit} monitor command (or qemu-img commit).
+
+If a relative path name is given, the backing file is looked up relative to
+the directory containing @var{filename}.
+
+Note that a given backing file will be opened to check that it is valid. Use
+the @code{-u} option to enable unsafe backing file mode, which means that the
+image will be created even if the associated backing file cannot be opened. A
+matching backing file must be created or additional options be used to make the
+backing file specification valid when you want to use an image created this
+way.
+
+The size can also be specified using the @var{size} option with @code{-o},
+it doesn't need to be specified separately in this case.
+
 @item dd [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
 
 Dd copies from @var{input} file to @var{output} file converting it from
@@ -585,10 +591,6 @@ how the additional image area should be allocated on the host.  See the format
 description in the @code{NOTES} section which values are allowed.  Using this
 option may result in slightly more data being allocated than necessary.
 
-@item amend [-p] [-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.
 @end table
 @c man end
 
-- 
2.14.3

[Qemu-devel] [PATCH 3/5] qemu-img: remove references to GEN_DOCS

[John Snow]

Nothing seemingly uses this.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qemu-img.c             | 2 --
 qemu-options-wrapper.h | 1 -
 2 files changed, 3 deletions(-)

diff --git a/qemu-img.c b/qemu-img.c
index 855fa52514..a01425372d 100644
--- a/qemu-img.c
+++ b/qemu-img.c
@@ -123,7 +123,6 @@ static void QEMU_NORETURN help(void)
            "  " arg_string "\n"
 #include "qemu-img-cmds.h"
 #undef DEF
-#undef GEN_DOCS
            "\n"
            "Command parameters:\n"
            "  'filename' is a disk image filename\n"
@@ -4685,7 +4684,6 @@ static const img_cmd_t img_cmds[] = {
     { option, callback },
 #include "qemu-img-cmds.h"
 #undef DEF
-#undef GEN_DOCS
     { NULL, NULL, },
 };
 
diff --git a/qemu-options-wrapper.h b/qemu-options-wrapper.h
index 13bfea0294..6f548e3922 100644
--- a/qemu-options-wrapper.h
+++ b/qemu-options-wrapper.h
@@ -34,7 +34,6 @@
 #undef DEF
 #undef DEFHEADING
 #undef ARCHHEADING
-#undef GEN_DOCS
 
 #undef QEMU_OPTIONS_GENERATE_ENUM
 #undef QEMU_OPTIONS_GENERATE_HELP
-- 
2.14.3

[Qemu-devel] [PATCH 4/5] qemu-img: Make documentation between .texi and .hx consistent

[John Snow]

These are also different and out of order for whatever reason.
I'd like to automate this in the future, but for now let's put
on the band-aid.

In the case of resize, there were options missing from all
three docstrings; the new string is based on the code.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qemu-img-cmds.hx |  4 ++--
 qemu-img.texi    | 24 ++++++++++++------------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
index 8bcefcafe9..84deb858af 100644
--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -89,9 +89,9 @@ STEXI
 ETEXI
 
 DEF("resize", img_resize,
-    "resize [--object objectdef] [--image-opts] [-q] [--shrink] filename [+ | -]size")
+    "resize [--object objectdef] [--image-opts] [-f fmt] [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size")
 STEXI
-@item resize [--object @var{objectdef}] [--image-opts] [-q] [--shrink] @var{filename} [+ | -]@var{size}
+@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--preallocation=@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{size}
 ETEXI
 
 STEXI
diff --git a/qemu-img.texi b/qemu-img.texi
index adf5176902..2be8206a05 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -194,12 +194,12 @@ Command description:
 
 @table @option
 
-@item amend [-p] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
+@item amend [--object @var{objectdef}] [--image-opts] [-p] [-p] [-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.
 
-@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] @var{filename}
+@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] [-U] @var{filename}
 
 Run a simple sequential I/O benchmark on the specified image. If @code{-w} is
 specified, a write test is performed, otherwise a read test is performed.
@@ -223,7 +223,7 @@ specified as well.
 For write tests, by default a buffer filled with zeros is written. This can be
 overridden with a pattern byte specified by @var{pattern}.
 
-@item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] @var{filename}
+@item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{filename}
 
 Perform a consistency check on the disk image @var{filename}. The command can
 output in the format @var{ofmt} which is either @code{human} or @code{json}.
@@ -259,7 +259,7 @@ If @code{-r} is specified, exit codes representing the image state refer to the
 state after (the attempt at) repairing it. That is, a successful @code{-r all}
 will yield the exit code 0, independently of the image state before.
 
-@item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
+@item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
 
 Commit the changes recorded in @var{filename} in its base image or backing file.
 If the backing file is smaller than the snapshot, then the backing file will be
@@ -281,7 +281,7 @@ all images between @var{base} and the top image will be invalid and may return
 garbage data when read. For this reason, @code{-b} implies @code{-d} (so that
 the top image stays valid).
 
-@item compare [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-s] [-q] @var{filename1} @var{filename2}
+@item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{filename2}
 
 Check if two images have the same content. You can compare images with
 different format or settings.
@@ -322,7 +322,7 @@ Error on reading data
 
 @end table
 
-@item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-m @var{num_coroutines}] [-W] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
+@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}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename}
 
 Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated)
 to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c}
@@ -363,7 +363,7 @@ creating compressed images.
 @var{num_coroutines} specifies how many coroutines work in parallel during
 the convert process (defaults to 8).
 
-@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
+@item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
 
 Create the new disk image @var{filename} of size @var{size} and format
 @var{fmt}. Depending on the file format, you can add one or more @var{options}
@@ -387,7 +387,7 @@ way.
 The size can also be specified using the @var{size} option with @code{-o},
 it doesn't need to be specified separately in this case.
 
-@item dd [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
+@item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
 
 Dd copies from @var{input} file to @var{output} file converting it from
 @var{fmt} format to @var{output_fmt} format.
@@ -398,7 +398,7 @@ dd will stop reading input after reading @var{blocks} input blocks.
 
 The size syntax is similar to dd(1)'s size syntax.
 
-@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
+@item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] [-U] @var{filename}
 
 Give information about the disk image @var{filename}. Use it in
 particular to know the size reserved on disk which can be different
@@ -506,11 +506,11 @@ been written to all sectors.  This is the maximum size that the image file can
 occupy with the exception of internal snapshots, dirty bitmaps, vmstate data,
 and other advanced image format features.
 
-@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
+@item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename}
 
 List, apply, create or delete snapshots in image @var{filename}.
 
-@item rebase [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
+@item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
 
 Changes the backing file of an image. Only the formats @code{qcow2} and
 @code{qed} support changing the backing file.
@@ -570,7 +570,7 @@ qemu-img rebase -b base.img diff.qcow2
 At this point, @code{modified.img} can be discarded, since
 @code{base.img + diff.qcow2} contains the same information.
 
-@item resize [--shrink] [--preallocation=@var{prealloc}] @var{filename} [+ | -]@var{size}
+@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--preallocation=@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{size}
 
 Change the disk image as if it had been created with @var{size}.
 
-- 
2.14.3

[Qemu-devel] [PATCH 5/5] qemu-img-cmds.hx: add passive-aggressive note

[John Snow]

I'm kidding. It's very easy to forget there are per-command sections
in the texi, and insane that we don't autogenerate those, too.

Until then, leave a little post-it note in this .hx file until I
find a way to delete it.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qemu-img-cmds.hx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
index 84deb858af..3d2f7b26eb 100644
--- a/qemu-img-cmds.hx
+++ b/qemu-img-cmds.hx
@@ -6,6 +6,9 @@ HXCOMM DEF(command, callback, arg_string) is used to construct
 HXCOMM command structures and help message.
 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
 
+HXCOMM When amending the TEXI sections, please remember to copy the usage
+HXCOMM over to the per-command sections in qemu-img.texi.
+
 STEXI
 @table @option
 ETEXI
-- 
2.14.3

Re: [Qemu-devel] [PATCH 0/5] qemu-img: make subcommand usage docstrings consistent

[John Snow]

On 05/03/2018 06:56 PM, John Snow wrote:
> I'm working on a project to attempt to autogenerate all of this, but
> until then let's just do a bit of the usual kinds of tidying.
> 
> ________________________________________________________________________________
> 
> For convenience, this branch is available at:
> https://github.com/jnsnow/qemu.git branch trivial-qemu-img
> https://github.com/jnsnow/qemu/tree/trivial-qemu-img
> 
> This version is tagged trivial-qemu-img-v1:
> https://github.com/jnsnow/qemu/releases/tag/trivial-qemu-img-v1
> 
> John Snow (5):
>   qemu-img-commands.hx: argument ordering fixups
>   qemu-img.texi: fix command ordering
>   qemu-img: remove references to GEN_DOCS
>   qemu-img: Make documentation between .texi and .hx consistent
>   qemu-img-cmds.hx: add passive-aggressive note
> 
>  qemu-img-cmds.hx       | 13 +++++----
>  qemu-img.c             |  2 --
>  qemu-img.texi          | 78 ++++++++++++++++++++++++++------------------------
>  qemu-options-wrapper.h |  1 -
>  4 files changed, 48 insertions(+), 46 deletions(-)
> 

Possessed by some kind of malevolent phantasm, I documented the following:

amend	 [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
bench                                        [-q] [-f fmt] [-U] filename
check    [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
commit   [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
compare  [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
convert  [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
create   [--object objectdef]                [-q] [-f fmt]      filename
dd                            [--image-opts]      [-f fmt] [-U]
info     [--object objectdef] [--image-opts]      [-f fmt] [-U] filename
map      [--object objectdef] [--image-opts]      [-f fmt] [-U] filename
measure  [--object objectdef] [--image-opts]      [-f fmt]      filename
snapshot [--object objectdef] [--image-opts] [-q]          [-U] filename
rebase   [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
resize   [--object objectdef] [--image-opts] [-q] [-f fmt]      filename

These are the largely universal set of options we support on most
commands, except sometimes some commands don't support them. Maybe
that's intentional, Maybe it isn't:

- Maybe we don't really want -U on commands that are opened RDWR.
- Maybe -f fmt isn't useful on snapshot or amend (which only work for
qcow2?)
- Maybe -q is inherently pretty useless for commands like info, map, or
measure whose job is to show you something.

Less clear to me:

- Is there no place for --image-opts for create?
- Or --object for dd?
- Or either of these two for bench?


The thought, though, is to define some core set of options that will
always apply to all commands. It might not always be perfect, but the
arguments listed here are a start for what probably makes sense for most
commands. Maybe it's a bad idea; but maybe individual parsers could opt
out of the common set of arguments on an as-needed basis instead.

Might help the documentation along to be able to point to some
definitely universal core group of options.

--js

Re: [Qemu-devel] [Qemu-block] [PATCH 1/5] qemu-img-commands.hx: argument ordering fixups

[Jeff Cody]

On Thu, May 03, 2018 at 06:56:44PM -0400, John Snow wrote:
> The TEXI and string versions are actually identical, except for markup.
> We can probably automate this... but make the ordering the same until
> then.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>

Reviewed-by: Jeff Cody <jcody@redhat.com>

> ---
>  qemu-img-cmds.hx | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
> index 2fe31893cf..8bcefcafe9 100644
> --- a/qemu-img-cmds.hx
> +++ b/qemu-img-cmds.hx
> @@ -23,13 +23,13 @@ STEXI
>  ETEXI
>  
>  DEF("check", img_check,
> -    "check [-q] [--object objectdef] [--image-opts] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
> +    "check [--object objectdef] [--image-opts] [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] [-U] filename")
>  STEXI
>  @item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{filename}
>  ETEXI
>  
>  DEF("commit", img_commit,
> -    "commit [-q] [--object objectdef] [--image-opts] [-f fmt] [-t cache] [-b base] [-d] [-p] filename")
> +    "commit [--object objectdef] [--image-opts] [-q] [-f fmt] [-t cache] [-b base] [-d] [-p] filename")
>  STEXI
>  @item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
>  ETEXI
> @@ -47,7 +47,7 @@ STEXI
>  ETEXI
>  
>  DEF("create", img_create,
> -    "create [-q] [--object objectdef] [-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]")
>  STEXI
>  @item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
>  ETEXI
> -- 
> 2.14.3
> 
> 

Re: [Qemu-devel] [Qemu-block] [PATCH 2/5] qemu-img.texi: fix command ordering

[Jeff Cody]

On Thu, May 03, 2018 at 06:56:45PM -0400, John Snow wrote:
> This should match the summary ordering, which is alphabetical.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---

Reviewed-by: Jeff Cody <jcody@redhat.com>

>  qemu-img.texi | 58 ++++++++++++++++++++++++++++++----------------------------
>  1 file changed, 30 insertions(+), 28 deletions(-)
> 
> diff --git a/qemu-img.texi b/qemu-img.texi
> index 8a26400adb..adf5176902 100644
> --- a/qemu-img.texi
> +++ b/qemu-img.texi
> @@ -193,6 +193,12 @@ sets the number of input blocks to skip
>  Command description:
>  
>  @table @option
> +
> +@item amend [-p] [-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.
> +
>  @item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] @var{filename}
>  
>  Run a simple sequential I/O benchmark on the specified image. If @code{-w} is
> @@ -253,30 +259,6 @@ If @code{-r} is specified, exit codes representing the image state refer to the
>  state after (the attempt at) repairing it. That is, a successful @code{-r all}
>  will yield the exit code 0, independently of the image state before.
>  
> -@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
> -
> -Create the new disk image @var{filename} of size @var{size} and format
> -@var{fmt}. Depending on the file format, you can add one or more @var{options}
> -that enable additional features of this format.
> -
> -If the option @var{backing_file} is specified, then the image will record
> -only the differences from @var{backing_file}. No size needs to be specified in
> -this case. @var{backing_file} will never be modified unless you use the
> -@code{commit} monitor command (or qemu-img commit).
> -
> -If a relative path name is given, the backing file is looked up relative to
> -the directory containing @var{filename}.
> -
> -Note that a given backing file will be opened to check that it is valid. Use
> -the @code{-u} option to enable unsafe backing file mode, which means that the
> -image will be created even if the associated backing file cannot be opened. A
> -matching backing file must be created or additional options be used to make the
> -backing file specification valid when you want to use an image created this
> -way.
> -
> -The size can also be specified using the @var{size} option with @code{-o},
> -it doesn't need to be specified separately in this case.
> -
>  @item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
>  
>  Commit the changes recorded in @var{filename} in its base image or backing file.
> @@ -381,6 +363,30 @@ creating compressed images.
>  @var{num_coroutines} specifies how many coroutines work in parallel during
>  the convert process (defaults to 8).
>  
> +@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
> +
> +Create the new disk image @var{filename} of size @var{size} and format
> +@var{fmt}. Depending on the file format, you can add one or more @var{options}
> +that enable additional features of this format.
> +
> +If the option @var{backing_file} is specified, then the image will record
> +only the differences from @var{backing_file}. No size needs to be specified in
> +this case. @var{backing_file} will never be modified unless you use the
> +@code{commit} monitor command (or qemu-img commit).
> +
> +If a relative path name is given, the backing file is looked up relative to
> +the directory containing @var{filename}.
> +
> +Note that a given backing file will be opened to check that it is valid. Use
> +the @code{-u} option to enable unsafe backing file mode, which means that the
> +image will be created even if the associated backing file cannot be opened. A
> +matching backing file must be created or additional options be used to make the
> +backing file specification valid when you want to use an image created this
> +way.
> +
> +The size can also be specified using the @var{size} option with @code{-o},
> +it doesn't need to be specified separately in this case.
> +
>  @item dd [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
>  
>  Dd copies from @var{input} file to @var{output} file converting it from
> @@ -585,10 +591,6 @@ how the additional image area should be allocated on the host.  See the format
>  description in the @code{NOTES} section which values are allowed.  Using this
>  option may result in slightly more data being allocated than necessary.
>  
> -@item amend [-p] [-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.
>  @end table
>  @c man end
>  
> -- 
> 2.14.3
> 
> 

Re: [Qemu-devel] [Qemu-block] [PATCH 3/5] qemu-img: remove references to GEN_DOCS

[Jeff Cody]

On Thu, May 03, 2018 at 06:56:46PM -0400, John Snow wrote:
> Nothing seemingly uses this.
>

Indeed - it looks like it has been vestigial for a while now (commit
77bd1119ba even mentions that it appears unused).

Reviewed-by: Jeff Cody <jcody@redhat.com>

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qemu-img.c             | 2 --
>  qemu-options-wrapper.h | 1 -
>  2 files changed, 3 deletions(-)
> 
> diff --git a/qemu-img.c b/qemu-img.c
> index 855fa52514..a01425372d 100644
> --- a/qemu-img.c
> +++ b/qemu-img.c
> @@ -123,7 +123,6 @@ static void QEMU_NORETURN help(void)
>             "  " arg_string "\n"
>  #include "qemu-img-cmds.h"
>  #undef DEF
> -#undef GEN_DOCS
>             "\n"
>             "Command parameters:\n"
>             "  'filename' is a disk image filename\n"
> @@ -4685,7 +4684,6 @@ static const img_cmd_t img_cmds[] = {
>      { option, callback },
>  #include "qemu-img-cmds.h"
>  #undef DEF
> -#undef GEN_DOCS
>      { NULL, NULL, },
>  };
>  
> diff --git a/qemu-options-wrapper.h b/qemu-options-wrapper.h
> index 13bfea0294..6f548e3922 100644
> --- a/qemu-options-wrapper.h
> +++ b/qemu-options-wrapper.h
> @@ -34,7 +34,6 @@
>  #undef DEF
>  #undef DEFHEADING
>  #undef ARCHHEADING
> -#undef GEN_DOCS
>  
>  #undef QEMU_OPTIONS_GENERATE_ENUM
>  #undef QEMU_OPTIONS_GENERATE_HELP
> -- 
> 2.14.3
> 
> 

Re: [Qemu-devel] [Qemu-block] [PATCH 4/5] qemu-img: Make documentation between .texi and .hx consistent

[Jeff Cody]

On Thu, May 03, 2018 at 06:56:47PM -0400, John Snow wrote:
> These are also different and out of order for whatever reason.
> I'd like to automate this in the future, but for now let's put
> on the band-aid.
> 
> In the case of resize, there were options missing from all
> three docstrings; the new string is based on the code.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>

Reviewed-by: Jeff Cody <jcody@redhat.com>

> ---
>  qemu-img-cmds.hx |  4 ++--
>  qemu-img.texi    | 24 ++++++++++++------------
>  2 files changed, 14 insertions(+), 14 deletions(-)
> 
> diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
> index 8bcefcafe9..84deb858af 100644
> --- a/qemu-img-cmds.hx
> +++ b/qemu-img-cmds.hx
> @@ -89,9 +89,9 @@ STEXI
>  ETEXI
>  
>  DEF("resize", img_resize,
> -    "resize [--object objectdef] [--image-opts] [-q] [--shrink] filename [+ | -]size")
> +    "resize [--object objectdef] [--image-opts] [-f fmt] [--preallocation=prealloc] [-q] [--shrink] filename [+ | -]size")
>  STEXI
> -@item resize [--object @var{objectdef}] [--image-opts] [-q] [--shrink] @var{filename} [+ | -]@var{size}
> +@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--preallocation=@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{size}
>  ETEXI
>  
>  STEXI
> diff --git a/qemu-img.texi b/qemu-img.texi
> index adf5176902..2be8206a05 100644
> --- a/qemu-img.texi
> +++ b/qemu-img.texi
> @@ -194,12 +194,12 @@ Command description:
>  
>  @table @option
>  
> -@item amend [-p] [-f @var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
> +@item amend [--object @var{objectdef}] [--image-opts] [-p] [-p] [-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.
>  
> -@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] @var{filename}
> +@item bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] [--flush-interval=@var{flush_interval}] [-n] [--no-drain] [-o @var{offset}] [--pattern=@var{pattern}] [-q] [-s @var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] [-U] @var{filename}
>  
>  Run a simple sequential I/O benchmark on the specified image. If @code{-w} is
>  specified, a write test is performed, otherwise a read test is performed.
> @@ -223,7 +223,7 @@ specified as well.
>  For write tests, by default a buffer filled with zeros is written. This can be
>  overridden with a pattern byte specified by @var{pattern}.
>  
> -@item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] @var{filename}
> +@item check [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] [-T @var{src_cache}] [-U] @var{filename}
>  
>  Perform a consistency check on the disk image @var{filename}. The command can
>  output in the format @var{ofmt} which is either @code{human} or @code{json}.
> @@ -259,7 +259,7 @@ If @code{-r} is specified, exit codes representing the image state refer to the
>  state after (the attempt at) repairing it. That is, a successful @code{-r all}
>  will yield the exit code 0, independently of the image state before.
>  
> -@item commit [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
> +@item commit [--object @var{objectdef}] [--image-opts] [-q] [-f @var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
>  
>  Commit the changes recorded in @var{filename} in its base image or backing file.
>  If the backing file is smaller than the snapshot, then the backing file will be
> @@ -281,7 +281,7 @@ all images between @var{base} and the top image will be invalid and may return
>  garbage data when read. For this reason, @code{-b} implies @code{-d} (so that
>  the top image stays valid).
>  
> -@item compare [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-s] [-q] @var{filename1} @var{filename2}
> +@item compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-F @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} @var{filename2}
>  
>  Check if two images have the same content. You can compare images with
>  different format or settings.
> @@ -322,7 +322,7 @@ Error on reading data
>  
>  @end table
>  
> -@item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-O @var{output_fmt}] [-B @var{backing_file}] [-o @var{options}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-m @var{num_coroutines}] [-W] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
> +@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}] [-s @var{snapshot_id_or_name}] [-l @var{snapshot_param}] [-S @var{sparse_size}] [-m @var{num_coroutines}] [-W] @var{filename} [@var{filename2} [...]] @var{output_filename}
>  
>  Convert the disk image @var{filename} or a snapshot @var{snapshot_param}(@var{snapshot_id_or_name} is deprecated)
>  to disk image @var{output_filename} using format @var{output_fmt}. It can be optionally compressed (@code{-c}
> @@ -363,7 +363,7 @@ creating compressed images.
>  @var{num_coroutines} specifies how many coroutines work in parallel during
>  the convert process (defaults to 8).
>  
> -@item create [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
> +@item create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b @var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] @var{filename} [@var{size}]
>  
>  Create the new disk image @var{filename} of size @var{size} and format
>  @var{fmt}. Depending on the file format, you can add one or more @var{options}
> @@ -387,7 +387,7 @@ way.
>  The size can also be specified using the @var{size} option with @code{-o},
>  it doesn't need to be specified separately in this case.
>  
> -@item dd [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
> +@item dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] [bs=@var{block_size}] [count=@var{blocks}] [skip=@var{blocks}] if=@var{input} of=@var{output}
>  
>  Dd copies from @var{input} file to @var{output} file converting it from
>  @var{fmt} format to @var{output_fmt} format.
> @@ -398,7 +398,7 @@ dd will stop reading input after reading @var{blocks} input blocks.
>  
>  The size syntax is similar to dd(1)'s size syntax.
>  
> -@item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
> +@item info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] [-U] @var{filename}
>  
>  Give information about the disk image @var{filename}. Use it in
>  particular to know the size reserved on disk which can be different
> @@ -506,11 +506,11 @@ been written to all sectors.  This is the maximum size that the image file can
>  occupy with the exception of internal snapshots, dirty bitmaps, vmstate data,
>  and other advanced image format features.
>  
> -@item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
> +@item snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename}
>  
>  List, apply, create or delete snapshots in image @var{filename}.
>  
> -@item rebase [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
> +@item rebase [--object @var{objectdef}] [--image-opts] [-U] [-q] [-f @var{fmt}] [-t @var{cache}] [-T @var{src_cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
>  
>  Changes the backing file of an image. Only the formats @code{qcow2} and
>  @code{qed} support changing the backing file.
> @@ -570,7 +570,7 @@ qemu-img rebase -b base.img diff.qcow2
>  At this point, @code{modified.img} can be discarded, since
>  @code{base.img + diff.qcow2} contains the same information.
>  
> -@item resize [--shrink] [--preallocation=@var{prealloc}] @var{filename} [+ | -]@var{size}
> +@item resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [--preallocation=@var{prealloc}] [-q] [--shrink] @var{filename} [+ | -]@var{size}
>  
>  Change the disk image as if it had been created with @var{size}.
>  
> -- 
> 2.14.3
> 
> 

Re: [Qemu-devel] [Qemu-block] [PATCH 5/5] qemu-img-cmds.hx: add passive-aggressive note

[Jeff Cody]

On Thu, May 03, 2018 at 06:56:48PM -0400, John Snow wrote:
> I'm kidding. It's very easy to forget there are per-command sections
> in the texi, and insane that we don't autogenerate those, too.
> 
> Until then, leave a little post-it note in this .hx file until I
> find a way to delete it.
>

Hopefully helps, but as you said the real fix is autogeneration.

Reviewed-by: Jeff Cody <jcody@redhat.com>

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qemu-img-cmds.hx | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/qemu-img-cmds.hx b/qemu-img-cmds.hx
> index 84deb858af..3d2f7b26eb 100644
> --- a/qemu-img-cmds.hx
> +++ b/qemu-img-cmds.hx
> @@ -6,6 +6,9 @@ HXCOMM DEF(command, callback, arg_string) is used to construct
>  HXCOMM command structures and help message.
>  HXCOMM HXCOMM can be used for comments, discarded from both texi and C
>  
> +HXCOMM When amending the TEXI sections, please remember to copy the usage
> +HXCOMM over to the per-command sections in qemu-img.texi.
> +
>  STEXI
>  @table @option
>  ETEXI
> -- 
> 2.14.3
> 
> 

Re: [Qemu-devel] [Qemu-block] [PATCH 0/5] qemu-img: make subcommand usage docstrings consistent

[Max Reitz]

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

On 2018-05-04 03:03, John Snow wrote:
> On 05/03/2018 06:56 PM, John Snow wrote:
>> I'm working on a project to attempt to autogenerate all of this, but
>> until then let's just do a bit of the usual kinds of tidying.
>>
>> ________________________________________________________________________________
>>
>> For convenience, this branch is available at:
>> https://github.com/jnsnow/qemu.git branch trivial-qemu-img
>> https://github.com/jnsnow/qemu/tree/trivial-qemu-img
>>
>> This version is tagged trivial-qemu-img-v1:
>> https://github.com/jnsnow/qemu/releases/tag/trivial-qemu-img-v1
>>
>> John Snow (5):
>>   qemu-img-commands.hx: argument ordering fixups
>>   qemu-img.texi: fix command ordering
>>   qemu-img: remove references to GEN_DOCS
>>   qemu-img: Make documentation between .texi and .hx consistent
>>   qemu-img-cmds.hx: add passive-aggressive note
>>
>>  qemu-img-cmds.hx       | 13 +++++----
>>  qemu-img.c             |  2 --
>>  qemu-img.texi          | 78 ++++++++++++++++++++++++++------------------------
>>  qemu-options-wrapper.h |  1 -
>>  4 files changed, 48 insertions(+), 46 deletions(-)
>>
> 
> Possessed by some kind of malevolent phantasm, I documented the following:
> 
> amend	 [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
> bench                                        [-q] [-f fmt] [-U] filename
> check    [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> commit   [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
> compare  [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> convert  [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> create   [--object objectdef]                [-q] [-f fmt]      filename
> dd                            [--image-opts]      [-f fmt] [-U]
> info     [--object objectdef] [--image-opts]      [-f fmt] [-U] filename
> map      [--object objectdef] [--image-opts]      [-f fmt] [-U] filename
> measure  [--object objectdef] [--image-opts]      [-f fmt]      filename
> snapshot [--object objectdef] [--image-opts] [-q]          [-U] filename
> rebase   [--object objectdef] [--image-opts] [-q] [-f fmt] [-U] filename
> resize   [--object objectdef] [--image-opts] [-q] [-f fmt]      filename
> 
> These are the largely universal set of options we support on most
> commands, except sometimes some commands don't support them. Maybe
> that's intentional, Maybe it isn't:
> 
> - Maybe we don't really want -U on commands that are opened RDWR.

Sounds reasonable to me.

> - Maybe -f fmt isn't useful on snapshot or amend (which only work for
> qcow2?)

But amend does have -f fmt.  I suppose snapshot should as well.

> - Maybe -q is inherently pretty useless for commands like info, map, or
> measure whose job is to show you something.

I suppose so, too.  If it was an option, it just wouldn’t do anything.
That’s OK to me if you plan to add it as a global option, but it isn’t
really useful.

> Less clear to me:
> 
> - Is there no place for --image-opts for create?

Not yet.  When x-blockdev-create loses its x-, it might be the time to
change that.

The same holds true for convert, by the way.  Its --image-opts is only
usable for the source, but there is no --target-image-opts.  That’s
because currently you always need a filename for image creation, and you
just can give some creation options in addition (through -o).

It might be useful for bench, but that’s debugging anyway, so I don’t
really care.

> - Or --object for dd?

I’d rather not see any changes to dd.  Actually, I’d rather not see dd
at all, but that’s a personal opinion.

I’ve always wanted to merge dd’s functionality into convert, so the less
it can do until then, the better, I suppose.  (Though of course I’ve
never had the time to attack this issue, as usual.)

> - Or either of these two for bench?

Again, it’s solely for debugging, so feel free to go wild, but there’s
no actual need to support it until any of us developers wants to use it
with luks.

Shouldn’t be that hard, anyway.

Max

> The thought, though, is to define some core set of options that will
> always apply to all commands. It might not always be perfect, but the
> arguments listed here are a start for what probably makes sense for most
> commands. Maybe it's a bad idea; but maybe individual parsers could opt
> out of the common set of arguments on an as-needed basis instead.
> 
> Might help the documentation along to be able to point to some
> definitely universal core group of options.
> 
> --js
> 
> 



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