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

[Peter Maydell]

On Tue, 25 Feb 2020 at 18:28, Paolo Bonzini <address@hidden> 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