[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-block] [PATCH RFC 0/3] qemu-img: remove command documentation
From: |
John Snow |
Subject: |
Re: [Qemu-block] [PATCH RFC 0/3] qemu-img: remove command documentation duplication |
Date: |
Wed, 26 Jun 2019 14:07:53 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.7.0 |
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