[Qemu-block] [PATCH RFC 3/3] qemu-img.texi: use macros for command summaries

[John Snow]

Use a macro to recall this text instead of re-entering it manually.

Modify the pxtool script to create macros for each subcommand, then
alter the qemu-img.texi file to recall these macros.

Signed-off-by: John Snow <address@hidden>
---
 qemu-img.texi     | 28 ++++++++++++++--------------
 scripts/pxtool.py |  4 ++++
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index 724f244ba1..c21a97e934 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -197,12 +197,12 @@ Command description:
 
 @table @option
 
address@hidden amend [--object @var{objectdef}] [--image-opts] [-p] [-q] [-f 
@var{fmt}] [-t @var{cache}] -o @var{options} @var{filename}
address@hidden
 
 Amends the image format specific @var{options} for the image file
 @var{filename}. Not all file formats support this operation.
 
address@hidden bench [-c @var{count}] [-d @var{depth}] [-f @var{fmt}] 
address@hidden [-n] [--no-drain] [-o @var{offset}] address@hidden [-q] [-s 
@var{buffer_size}] [-S @var{step_size}] [-t @var{cache}] [-w] [-U] 
@var{filename}
address@hidden
 
 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.
@@ -226,7 +226,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}.
 
address@hidden check [--object @var{objectdef}] [--image-opts] [-q] [-f 
@var{fmt}] address@hidden [-r [leaks | all]] [-T @var{src_cache}] [-U] 
@var{filename}
address@hidden
 
 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}.
@@ -262,7 +262,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.
 
address@hidden commit [--object @var{objectdef}] [--image-opts] [-q] [-f 
@var{fmt}] [-t @var{cache}] [-b @var{base}] [-d] [-p] @var{filename}
address@hidden
 
 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
@@ -284,7 +284,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).
 
address@hidden compare [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] 
[-F @var{fmt}] [-T @var{src_cache}] [-p] [-q] [-s] [-U] @var{filename1} 
@var{filename2}
address@hidden
 
 Check if two images have the same content. You can compare images with
 different format or settings.
@@ -325,7 +325,7 @@ Error on reading data
 
 @end table
 
address@hidden 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} address@hidden [...]] 
@var{output_filename}
address@hidden
 
 Convert the disk image @var{filename} or a snapshot @var{snapshot_param}
 to disk image @var{output_filename} using format @var{output_fmt}. It can be 
optionally compressed (@code{-c}
@@ -366,7 +366,7 @@ creating compressed images.
 @var{num_coroutines} specifies how many coroutines work in parallel during
 the convert process (defaults to 8).
 
address@hidden create [--object @var{objectdef}] [-q] [-f @var{fmt}] [-b 
@var{backing_file}] [-F @var{backing_fmt}] [-u] [-o @var{options}] 
@var{filename} address@hidden
address@hidden
 
 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}
@@ -390,7 +390,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.
 
address@hidden dd [--image-opts] [-U] [-f @var{fmt}] [-O @var{output_fmt}] 
address@hidden address@hidden address@hidden address@hidden address@hidden
address@hidden
 
 Dd copies from @var{input} file to @var{output} file converting it from
 @var{fmt} format to @var{output_fmt} format.
@@ -401,7 +401,7 @@ dd will stop reading input after reading @var{blocks} input 
blocks.
 
 The size syntax is similar to dd(1)'s size syntax.
 
address@hidden info [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] 
address@hidden [--backing-chain] [-U] @var{filename}
address@hidden
 
 Give information about the disk image @var{filename}. Use it in
 particular to know the size reserved on disk which can be different
@@ -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
 
address@hidden map [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] 
address@hidden [-U] @var{filename}
address@hidden
 
 Dump the metadata of image @var{filename} and its backing file chain.
 In particular, this commands dumps the allocation state of every sector
@@ -479,7 +479,7 @@ preallocated.
 For more information, consult @file{include/block/block.h} in QEMU's
 source code.
 
address@hidden measure address@hidden [-O @var{output_fmt}] [-o @var{options}] 
[--size @var{N} | [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] [-l 
@var{snapshot_param}] @var{filename}]
address@hidden
 
 Calculate the file size required for a new image.  This information can be used
 to size logical volumes or SAN LUNs appropriately for the image that will be
@@ -509,11 +509,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.
 
address@hidden snapshot [--object @var{objectdef}] [--image-opts] [-U] [-q] [-l 
| -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot}] @var{filename}
address@hidden
 
 List, apply, create or delete snapshots in image @var{filename}.
 
address@hidden 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}
address@hidden
 
 Changes the backing file of an image. Only the formats @code{qcow2} and
 @code{qed} support changing the backing file.
@@ -573,7 +573,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.
 
address@hidden resize [--object @var{objectdef}] [--image-opts] [-f @var{fmt}] 
address@hidden [-q] [--shrink] @var{filename} [+ | address@hidden
address@hidden
 
 Change the disk image as if it had been created with @var{size}.
 
diff --git a/scripts/pxtool.py b/scripts/pxtool.py
index 008fea839e..7ed5550b29 100755
--- a/scripts/pxtool.py
+++ b/scripts/pxtool.py
@@ -30,7 +30,11 @@ def generate_texi(conf):
     print("@table @option")
     for command, usage_strs in conf.items():
         usage = " ".join(usage_strs)
+        macro = "qemuimgcmd{}".format(command)
+        print("@macro {}".format(macro))
         print("@item {} {}".format(command, usage))
+        print("@end macro")
+        print("@{}".format(macro))
     print("@end table")
 
 if __name__ == '__main__':
-- 
2.17.2