On Tue, 25 Feb 2020 at 18:28, Paolo Bonzini <pbonz...@redhat.com> wrote: > > 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?
Yes, but until we complete the conversion we can't get rid of the qemu-doc.html output, because that's where the HTML output from the QAPI doc generation goes. > > 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. To be fair on the automated conversion, the markup in the source texinfo here is suboptimal :-) > > 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. Yeah, seems like a good plan. If the autoconversion works out then I think the main thing which makes "do all this for 5.0" at risk currently is that the qapidoc conversion series needs review and might need overhauling based on that review: it doesn't take many cycles of review-and-fix to push close to the softfreeze deadline. What do you want to do with this patchset? thanks -- PMM