On 24/09/2018 20:44, Markus Armbruster wrote: > Paolo Bonzini <pbonz...@redhat.com> writes: > >> On 24/09/2018 15:12, Peter Maydell wrote: >>> It got bumped by more important things >>> and also because somebody else said they were going to look at it, >>> and then it got bumped off *their* todo list by more important >>> things :-)) >> >> I sense the force calling me... Well, my plans were did not actually >> involve GTKDoc and the developer documentation, but rather the rest of >> the manual. What I wanted to do, but didn't manage to do, was to work >> on a new table of contents for the manual (not so much for the developer >> documentation), so that it could be converted to rST and generated with >> Sphinx. Converting Texinfo to rST is not trivial, but it seems doable >> via makeinfo's Docbook backend and pandoc. > > Remind me, why would rST be an improvement?
Personally I don't think it is an improvement over Texinfo, I find it to be the Perl of ASCII-based markups. :) In fact in my infamous poll (the one where I asked "which one would be hard to read/write before and after showing an example), Texinfo was the only one that got a better score after showing an example, and rST was the only one that got a worse score after the example. Still, rST got a higher score than Texinfo so others disagree with me and you. However, we currently have the worst of both worlds. We have a manual in Texinfo that almost nobody updates (except for the small parts that are generated from .hx files in the code) and sparse documentation written in a mix of rST, Markdown-but-not-quite, and not-even-trying-to-be-Markdown. The main disadvantage of Texinfo is that it's insanely hard to parse; it's pretty much the only format for which pandoc has a producer but not a reader. The silver lining is that makeinfo can produce both some strange XML and Docbook, but still connecting Texinfo to Sphinx rrequired a combination of Makeinfo to convert it to Docbook, XSLT to split the resulting file by chapter, and then a custom Sphinx parser for Docbook. The result was pretty good (http://people.redhat.com/pbonzini/qemu-test-doc/_build/html/) but I'm not sure I want to inflict that on the community, I've already used all my karma on block comment style. :) Paolo >> (I still don't like rST, but I guess that ship has sailed, also because >> Linux's scripts/kernel-doc has since dropped all backends but rST and >> man, so my other experiment of a Texinfo/Docbook backend for Sphinx is >> dead). >> >> Paolo >
