This might hopefully cut down on the doc duplication/mismatching
until I can devise something more comprehensive.

Ideally, I'd like to redo all of the documentation for qemu-img
nearly from scratch; with a parser generator that helps generate
the documentation as well so they'll never get out of date.

That's probably quite a ways off, and maybe there are other
structural changes we want to make with respect to sphinx and
other build tools, so I am sending something very minimal instead.

This ought to be functionally identical down to the last char.

(I've re-included patch one which I have sent to the list separately,
purely as a dependency if you want to apply these patches.)

John Snow (3):
  qemu-img: fix .hx and .texi disparity
  pxtool: Add new qemu-img command info generation tool
  qemu-img.texi: use macros for command summaries

 qemu-img.texi      |  28 ++++----
 Makefile           |   8 +--
 qemu-img-cmds.json | 165 +++++++++++++++++++++++++++++++++++++++++++++
 qemu-img-cmds.hx   | 102 ----------------------------
 scripts/pxtool.py  |  53 +++++++++++++++
 5 files changed, 236 insertions(+), 120 deletions(-)
 create mode 100644 qemu-img-cmds.json
 delete mode 100644 qemu-img-cmds.hx
 create mode 100755 scripts/pxtool.py

-- 
2.17.2

On 10.04.19 03:24, John Snow wrote:
> This might hopefully cut down on the doc duplication/mismatching
> until I can devise something more comprehensive.
> 
> Ideally, I'd like to redo all of the documentation for qemu-img
> nearly from scratch; with a parser generator that helps generate
> the documentation as well so they'll never get out of date.
> 
> That's probably quite a ways off, and maybe there are other
> structural changes we want to make with respect to sphinx and
> other build tools, so I am sending something very minimal instead.
> 
> This ought to be functionally identical down to the last char.
> 
> (I've re-included patch one which I have sent to the list separately,
> purely as a dependency if you want to apply these patches.)
> 
> John Snow (3):
>   qemu-img: fix .hx and .texi disparity
>   pxtool: Add new qemu-img command info generation tool
>   qemu-img.texi: use macros for command summaries

Hm.  Non-RFC ping?

Max

On 6/26/19 2:03 PM, Max Reitz wrote:
> On 10.04.19 03:24, John Snow wrote:
>> This might hopefully cut down on the doc duplication/mismatching
>> until I can devise something more comprehensive.
>>
>> Ideally, I'd like to redo all of the documentation for qemu-img
>> nearly from scratch; with a parser generator that helps generate
>> the documentation as well so they'll never get out of date.
>>
>> That's probably quite a ways off, and maybe there are other
>> structural changes we want to make with respect to sphinx and
>> other build tools, so I am sending something very minimal instead.
>>
>> This ought to be functionally identical down to the last char.
>>
>> (I've re-included patch one which I have sent to the list separately,
>> purely as a dependency if you want to apply these patches.)
>>
>> John Snow (3):
>>   qemu-img: fix .hx and .texi disparity
>>   pxtool: Add new qemu-img command info generation tool
>>   qemu-img.texi: use macros for command summaries
> 
> Hm.  Non-RFC ping?
> 
> Max
> 

This was mostly a quick hack; it didn't seek to eliminate ALL of the .hx
files we have, and it's not a comprehensive solution.

It is a quick stopgap that should work well enough for now, but it's
replacing one hack with another hack.

...Well, this hack is SLIGHTLY nicer, but I think I did some silly
things like using a zero-argument macro for texi instead of just
defining a variable. I don't know what I'm doing with texi stuff.

And then since I wrote it, there's been more buzz about reworking the
Sphinx documentation, so maybe this is too lateral of a move. I don't know.

I don't think it got review from the QAPI powers, though, and I think
I'd like to hear what they have to say before I invest any more time in
trying to fix this up.

--js