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

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Tue, 25 Feb 2020 at 17:48, Paolo Bonzini <pbonzini@redhat.com> wrote:
>>
>> On 25/02/20 18:11, Peter Maydell wrote:
>> >> I assume these are not meant to be applied now, except patch 2?
>> > No, I intended them to be reviewable and applied now. Why
>> > do you think we should wait?
>>
>> Because they remove information from qemu-doc.texi.  I think it's
>> feasible to do a mass conversion quite soon, within a single pull
>> request, the only important part that is missing is the hxtool conversion.
>
> 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)

Not true.  QAPI doc comments go into *separate* manuals, the "QEMU QMP
reference" (docs/interop/qemu-qmp-ref.*), and the "QEMU Guest Agent
protocol reference" (docs/interop/qemu-ga-ref.*).

In more detail: scripts/qapi-gen.py generates
docs/interop/qemu-qmp-qapi.texi from qapi/qapi-schema.json, and
docs/interop/qemu-ga-qapi.texi from qga/qapi-schema.json.  These are
included into docs/interop/qemu-qmp-ref.texi and
docs/interop/qemu-ga-ref.texi, respectively.

>  * convert the manpage parts; we have the machinery for dealing
>    with the hxtool files, it just needs a little more work
[...]