John Snow writes:
> On Thu, Mar 13, 2025 at 2:54 AM Markus Armbruster wrote:
>
>> John Snow writes:
>>
>> > This also creates the `qapi-qsd-index` and `qapi-qga-index` QMP indices.
>> >
>> > Signed-off-by: John Snow
>>
>> [...]
>>
>> > diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
>> > index 995594aaf43..35ec0e7db31 100644
>> > --- a/qga/qapi-schema.json
>> > +++ b/qga/qapi-schema.json
>> > @@ -3,6 +3,9 @@
>> >
>> > ##
>> > # = QEMU guest agent protocol commands and structs
>> > +#
>> > +# For a concise listing of all commands, events, and types in the QEMU
>> > +# guest agent, please consult the `qapi-qga-index`.
>> > ##
>> >
>> > { 'pragma': { 'doc-required': true } }
>> > diff --git a/storage-daemon/qapi/qapi-schema.json
>> > b/storage-daemon/qapi/qapi-schema.json
>> > index f10c9494906..2a562ee32e5 100644
>> > --- a/storage-daemon/qapi/qapi-schema.json
>> > +++ b/storage-daemon/qapi/qapi-schema.json
>> > @@ -13,6 +13,14 @@
>> > # the array type in the main schema, even if it is unused outside of the
>> > # storage daemon.
>> >
>> > +##
>> > +# = QEMU storage daemon protocol commands and structs
>> > +#
>> > +# For a concise listing of all commands, events, and types in the QEMU
>> > +# storage daemon, please consult the `qapi-qsd-index`.
>> > +##
>> > +
>> > +
>> > { 'include': '../../qapi/pragma.json' }
>> >
>> > # Documentation generated with qapi-gen.py is in source order, with
>>
>> Compare qapi/qapi-schema.json:
>>
>># = Introduction
>>#
>># This document describes all commands currently supported by QMP.
>>#
>># For locating a particular item, please see the `qapi-qmp-index`.
>>#
>>
>> Suggest to pick one phrasing and stick to it, unless there's a reason
>> for more than one.
>>
>
> Nope, just free-handing it. What's your favorite? ;)
Let me see...
Alright, I saw, and I hate what I saw. But addressing that should not
be coupled to this series. I'm going to take your patch as is, and
improve on top.
"But what exactly do you hate?" you might ask. Have a look at how the
three rendered manuals look like.
1. QMP (docs/manual/interop/qemu-qmp-ref.html)
QEMU QMP Reference Manual
*
Contents
* QEMU QMP Reference Manual
* Introduction
* QMP errors
[More entries at this level, namely all the modules...]
Introduction
This document describes all commands currently supported by QMP.
For locating a particular item, please see the QMP Index.
Most of the time their usage is exactly the same as in the user
Monitor, this means that any other document which also describe
commands (the manpage, QEMU's manual, etc) can and should be
consulted.
QMP has two types of commands: regular and query commands. Regular
commands usually change the Virtual Machine's state someway, while
query commands just return information. The sections below are
divided accordingly.
It's important to observe that all communication examples are
formatted in a reader-friendly way, so that they're easier to
understand. However, in real protocol usage, they're emitted as a
single line.
Also, the following notation is used to denote data flow:
Example:
-> data issued by the Client
<- Server data response
Please refer to the QEMU Machine Protocol Specification for detailed
information on the Server command and response formats.
QMP errors
==
[...]
The manual has a single top-level section, named like the manual. WTF?
The introduction reads fine, except it should be "all commands and
events".
2. QSD
QEMU Storage Daemon QMP Reference Manual
Contents
* QEMU Storage Daemon QMP Reference Manual
* QEMU storage daemon protocol commands and structs
* Common data types
[More entries at this level, namely all the modules...]
QEMU storage daemon protocol commands and structs
=
For a concise listing of all commands, events, and types in the QEMU
storage daemon, please consult the QSD Index.
Common data types
=
Same section structure WTF as above.
The introduction section is crap, starting with the title.
3. QGA
QEMU Guest Agent Protocol Reference
***
Contents
* QEMU Guest Agent Protocol Reference
* QEMU guest agent protocol commands and structs
QEMU guest agent protocol commands and structs
==
For a concise listing of all commands, events, and types in the QEMU
guest agent, please consult the QGA Index.
Command guest-sync-delimited (Since: 1.1)
Echo back a unique integer value, and prepend to response a leading
sentinel byte (0xFF) the client ca
