Re: [PATCH 0/3] docs: Create a 'tools' manual

[Peter Maydell]

On Mon, 17 Feb 2020 at 16:04, Paolo Bonzini <address@hidden> wrote:
>
> On 17/02/20 16:54, Peter Maydell wrote:
> > This patchset creates the new 'tools' manual that we've
> > decided we should have, and moves 5 existing documents to it:
> >
> >  docs/interop/qemu-img.rst
> >  docs/interop/qemu-nbd.rst
> >  docs/interop/virtfs-proxy-helper.rst
> >  docs/interop/qemu-trace-stap.rst
> >  docs/interop/virtiofsd.rst
> >
> > This change will conflict with the QAPI-doc-comment-to-rST
> > patchset because they both change the docs/interop makefile
> > rules, but I expect this one to get in to master first;
> > the other needs a respin at some point anyhow.
>
> Acked-by: Paolo Bonzini <address@hidden>
>
> We can move them back to the system manual once it's converted to rST,
> but for now it's the best solution.

I think they can reasonably continue to live in tools/
even once we've got more stuff in system/.

> (In fact, I am willing to do the conversion from texi to rST if: 1)
> someone else helps with the .hx parts; 2) we accept that the current
> structure of the manual isn't great but we agree to reorganize
> everything after the conversion).

Yes, I'm definitely working on a "we can reshuffle stuff
later, but let's get the basic conversion done first" basis.

The mechanics for handling .hx files are already in the tree;
I can either help or work on the bit of qemu.1 that uses those.

Kashyap has volunteered to do qemu-cpu-models.texi.
I have patches on-list that try to do the QAPI doc-comments.

I think the next thing after this is to take chunks of documentation
that are currently used in qemu-doc.html but not put into the
qemu.1 manpage (ie which aren't in the 'man begin'/'man end'
sections), and convert those into individual .rst files
to go into docs/system:

 * docs/security.texi
 * qemu-tech.texi
 * qemu-deprecated.texi
 * various bits of qemu-doc.texi that don't go in the
   manpage and that are coherent chunks of documentation,
   eg "Supported build platforms", the various "$ARCH System emulator"
   sections

That will whittle qemu-doc.texi down to more or less just
the contents of the manpage. Then we can convert that
part to rST.

I note that softfreeze is now 1 month away -- we should
decide whether we think we can get this basically all
done by then, or whether there's a good "pause point"
we'd like to use where, say, most of qemu-doc.texi
remains as it is, or where it retains just the
content that goes into the qemu.1 manpage.

thanks
-- PMM