[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 0/4] docs: Miscellaneous rST conversions
From: |
Paolo Bonzini |
Subject: |
Re: [PATCH 0/4] docs: Miscellaneous rST conversions |
Date: |
Tue, 25 Feb 2020 19:28:18 +0100 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 |
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
- [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/25
- [PATCH 2/4] docs: Remove the "CPU emulation" part of the "Implementation notes", Peter Maydell, 2020/02/25
- [PATCH 3/4] docs: Convert 'managed start up options' docs to rST, Peter Maydell, 2020/02/25
- [PATCH 1/4] docs: Convert security.texi to rST format, Peter Maydell, 2020/02/25
- [PATCH 4/4] docs: Convert qemu-deprecated.texi to rST, Peter Maydell, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Paolo Bonzini, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Paolo Bonzini, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions,
Paolo Bonzini <=
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Paolo Bonzini, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Paolo Bonzini, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/25
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Markus Armbruster, 2020/02/26
- Re: [PATCH 0/4] docs: Miscellaneous rST conversions, Peter Maydell, 2020/02/26