Re: [Qemu-devel] [PATCH RFC 0/3] qemu-img: remove command documentation duplication

[John Snow]

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