Re: [PATCH 0/4] docs: Miscellaneous rST conversions

[Paolo Bonzini <pbonzini@redhat.com>]

On 25/02/20 18:59, Peter Maydell wrote:
> My assumption was that we would attack this by:
>  * converting chunks of the documentation which are in qemu-doc.texi
>    but which aren't in the qemu.1 manpage (basically in the way this
>    series is doing)
>  * get the qapidoc generation conversion reviewed and into
>    master (since at the moment it outputs into files included
>    from qemu-doc)

The QAPI docs are in other manuals in docs/interop/, aren't they?

>  * convert the manpage parts; we have the machinery for dealing
>    with the hxtool files, it just needs a little more work
>
>> (See also the patches I posted today, which take the opposite direction
>> of making qemu-doc.texi's structure more like what we'll have in the end
>> in docs/system).
> 
> This ought to make it easier to do the conversion of the
> various subparts, right?

Right, and easier to review as well; I called it "the opposite
direction" because the editing is done in Texinfo format and the rST
conversion becomes relatively trivial.  This would make it possible to
do the conversion in a branch and pull it all at once (apart from
qapidoc and possibly other small changes like removing obsolete parts).

> Incidentally:
>> makeinfo -o - --docbook security.texi  | pandoc -f docbook -t rst
> security texi was the really easy one here. I had to do more
> manual formatting fixups on qemu-deprecated.texi which I'm
> sceptical would have worked out as nicely done automatically.

The automated conversion of qemu-deprecated.texi is indeed bad because
the titles in the source are missing @code{...} to activate monospaced
characters.

> The automatic conversion rune also doesn't seem to get quotes
> and apostrophes right: it has turned "guest B's disk image" into
> something with a smartquote character in it, for instance.

We probably don't want smartquotes at all, so you'd use "-t rst+smart"
as the destination.  Also pandoc does not use the "::" at the end of the
previous paragraph.  That can be fixed with for example

  perl -e '$/=undef; $_ = <>; s/:\n\n::/::/g; print'

In general the result is more than acceptable, and I'd rather get a
quick-and-slightly-dirty conversion done quickly than do everything
manually but risk missing 5.0.

Paolo