Re: [Qemu-devel] [PATCH v6 10/25] replay: introduce breakpoint at the specified step

[Paolo Bonzini]

On 24/09/2018 20:44, Markus Armbruster wrote:
> Paolo Bonzini <address@hidden> 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
>