Message ID | 20190410012413.31569-1-jsnow@redhat.com (mailing list archive) |
---|---|
Headers | show |
Series | qemu-img: remove command documentation duplication | expand |
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