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
