v4:
 - Added r-b's from various folks
 - Dropped a few conversion cases that were just simply not trivial enough.

   If you are a non-qapi/non-docs maintainer being CC'd on this patch,
   there is **very likely** nothing for you to do here; we are only
   changing spacing and syntax, but not modifying content in any way
   in this series in particular. Please feel free to mark-as-read and
   move on with your day.

v3:
   As per Markus' request, the intro section conversion has been split
   even further into the *very* trivial; leaving the semi-trivial and
   not-trivial conversions for later consideration.

-

Hi, this patchset converts trivial "introductory" sections in the QAPI
documentation to use the new, explicit intro section syntax.

This is being done primarily for the benefit of the forthcoming
"inliner", a feature for the rendered HTML QMP documentation that
seeks to "inline" QMP command argument documentation into the argument
list for each command.

There are two main motives here:

(1) We want the split between the "introduction" and "details"
    sections to be mechanically obvious, so that auto-generated or
    inlined documentation has a well-defined, obvious spot to go.

(2) We do not want to inline irrelevant, introductory text describing
    structures to be copied into command documentation.

This patchset tackles "very trivial" conversions: cases where the
existing leading plaintext is only a single sentence and is
immediately followed by a tagged section, the end of the documentation
block, or some other pre-existing syntactical delineation. (i.e.: not
more plaintext.)

NOTE: This series *may* miss some conversions; future QAPI changes will
enforce the new syntax and any cases that have appeared since v1 will
be identified and corrected at that time; we are concerned with the
bulk and ease-of-review here, not completeness. This is precisely why
the new intro syntax and parser were carefully designed to allow
gradual conversion.

NOTE2: Future patches that may require more scrutiny will handle the
remaining conversions - There are some very subtle concerns that are
not readily apparent in the very minor textual changes that will be
spelled out for reviewers in the cover letters for those series.

This is enough for today, don't you think?

John Snow (43):
  qapi: convert trivial intro sections for error.json
  qapi: convert trivial intro sections for acpi-hest.json
  qapi: convert trivial intro sections for ebpf.json
  qapi: convert trivial intro sections for compat.json
  qapi: convert trivial intro sections for vfio.json
  qapi: convert trivial intro sections for trace.json
  qapi: convert trivial intro sections for misc-arm.json
  qapi: convert trivial intro sections for cryptodev.json
  qapi: convert trivial intro sections for machine-common.json
  qapi: convert trivial intro sections for accelerator.json
  qapi: convert trivial intro sections for authz.json
  qapi: convert trivial intro sections for yank.json
  qapi: convert trivial intro sections for replay.json
  qapi: convert trivial intro sections for machine-s390x.json
  qapi: convert trivial intro sections for acpi.json
  qapi: convert trivial intro sections for tpm.json
  qapi: convert trivial intro sections for qdev.json
  qapi: convert trivial intro sections for control.json
  qapi: convert trivial intro sections for dump.json
  qapi: convert trivial intro sections for common.json
  qapi: convert trivial intro sections for sockets.json
  qapi: convert trivial intro sections for transaction.json
  qapi: convert trivial intro sections for stats.json
  qapi: convert trivial intro sections for job.json
  qapi: convert trivial intro sections for pci.json
  qapi: convert trivial intro sections for introspect.json
  qapi: convert trivial intro sections for rocker.json
  qapi: convert trivial intro sections for misc-i386.json
  qapi: convert trivial intro sections for block-export.json
  qapi: convert trivial intro sections for audio.json
  qapi: convert trivial intro sections for block.json
  qapi: convert trivial intro sections for misc.json
  qapi: convert trivial intro sections for crypto.json
  qapi: convert trivial intro sections for cxl.json
  qapi: convert trivial intro sections for run-state.json
  qapi: convert trivial intro sections for char.json
  qapi: convert trivial intro sections for virtio.json
  qapi: convert trivial intro sections for net.json
  qapi: convert trivial intro sections for qom.json
  qapi: convert trivial intro sections for ui.json
  qapi: convert trivial intro sections for migration.json
  qapi: convert trivial intro sections for machine.json
  qapi: convert trivial intro sections for block-core.json

 qapi/accelerator.json    |  18 +-
 qapi/acpi-hest.json      |   4 +-
 qapi/acpi.json           |   8 +-
 qapi/audio.json          |  88 +++-----
 qapi/authz.json          |  21 +-
 qapi/block-core.json     | 431 ++++++++++++++-------------------------
 qapi/block-export.json   |  50 ++---
 qapi/block.json          |  41 ++--
 qapi/char.json           |  90 +++-----
 qapi/common.json         |  29 +--
 qapi/compat.json         |   6 +-
 qapi/control.json        |  30 +--
 qapi/crypto.json         | 100 ++++-----
 qapi/cryptodev.json      |  18 +-
 qapi/cxl.json            |   6 +-
 qapi/dump.json           |  19 +-
 qapi/ebpf.json           |   6 +-
 qapi/error.json          |   3 +-
 qapi/introspect.json     |  40 ++--
 qapi/job.json            |  18 +-
 qapi/machine-common.json |  14 +-
 qapi/machine-s390x.json  |  13 +-
 qapi/machine.json        | 195 ++++++------------
 qapi/migration.json      | 131 +++++-------
 qapi/misc-arm.json       |   6 +-
 qapi/misc-i386.json      |  52 ++---
 qapi/misc.json           |  74 +++----
 qapi/net.json            |  92 +++------
 qapi/pci.json            |  27 +--
 qapi/qdev.json           |  14 +-
 qapi/qom.json            | 150 +++++---------
 qapi/replay.json         |   6 +-
 qapi/rocker.json         |  39 ++--
 qapi/run-state.json      | 113 ++++------
 qapi/sockets.json        |  31 ++-
 qapi/stats.json          |  34 ++-
 qapi/tpm.json            |  29 +--
 qapi/trace.json          |  12 +-
 qapi/transaction.json    |  14 +-
 qapi/ui.json             | 199 ++++++------------
 qapi/vfio.json           |   4 +-
 qapi/virtio.json         |  54 ++---
 qapi/yank.json           |   5 +-
 43 files changed, 833 insertions(+), 1501 deletions(-)

-- 
2.55.0

Series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

On Tue, Sep 1, 2026 at 7:05 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Series
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>

Thank you for your suffering :)

So, I think there's actually no real problem in checking in a partial
conversion as the infrastructure was coded specifically to allow it,
however you're the maintainer so I will follow your lead. I'm more
interested in moving forward than telling you how to do your job ;)

The series will eventually enforce strict ordering, so there is no
chance we will miss anything. If we send a PR now, we also don't have
to keep rebasing the partial series against master. If you don't want
to submit a PR, please create a branch I can track and submit patches
against, and please periodically rebase it against origin/master.

Thanks,
--js

John Snow <jsnow@redhat.com> writes:

> On Tue, Sep 1, 2026 at 7:05 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Series
>> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>>
>
> Thank you for your suffering :)

You're welcome; it's my job[*]!

> So, I think there's actually no real problem in checking in a partial
> conversion as the infrastructure was coded specifically to allow it,
> however you're the maintainer so I will follow your lead. I'm more
> interested in moving forward than telling you how to do your job ;)
>
> The series will eventually enforce strict ordering, so there is no
> chance we will miss anything. If we send a PR now, we also don't have
> to keep rebasing the partial series against master. If you don't want
> to submit a PR, please create a branch I can track and submit patches
> against, and please periodically rebase it against origin/master.

I worry a bit that having intros split about half between two styles
would cause confusion and friction.  I'd much prefer to get to >90%
fairly quickly.  If we think that's possible, I'm happy to queue up
things in my tree, and take care of the rebasing.


[*] Some days my compensation is compensation for suffering ;)

On Wed, Sep 2, 2026 at 6:58 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > On Tue, Sep 1, 2026 at 7:05 AM Markus Armbruster <armbru@redhat.com> wrote:
> >>
> >> Series
> >> Reviewed-by: Markus Armbruster <armbru@redhat.com>
> >>
> >
> > Thank you for your suffering :)
>
> You're welcome; it's my job[*]!
>
> > So, I think there's actually no real problem in checking in a partial
> > conversion as the infrastructure was coded specifically to allow it,
> > however you're the maintainer so I will follow your lead. I'm more
> > interested in moving forward than telling you how to do your job ;)
> >
> > The series will eventually enforce strict ordering, so there is no
> > chance we will miss anything. If we send a PR now, we also don't have
> > to keep rebasing the partial series against master. If you don't want
> > to submit a PR, please create a branch I can track and submit patches
> > against, and please periodically rebase it against origin/master.
>
> I worry a bit that having intros split about half between two styles
> would cause confusion and friction.  I'd much prefer to get to >90%
> fairly quickly.  If we think that's possible, I'm happy to queue up
> things in my tree, and take care of the rebasing.

Everything up until the "convert multi-paragraph intros" patch (#44 in
my pending work) is approximately 87% of the total volume of
conversions. In the most recent off-list mail I sent you, that's
Sections 1-7 -- which is essentially all of the stuff that was
factored out as "semi-trivial"/"simple", plus the "TODO" conversions.
I believe these are pretty trivial to burn through, but would require
a bit of dedicated time. We could probably do it in a week if we
really pushed ...

Existing volume of what you have reviewed and accepted is 55%.

Well, either way, I just don't want to have to juggle so many patches
in the interim, so I am pushing a bit to just merge it to make
subsequent series easier to rebase and juggle so that e.g. I don't
have to have increasingly long "based-on" tags.

(Makes sad, pouting noises.)

>
>
> [*] Some days my compensation is compensation for suffering ;)
>

John Snow <jsnow@redhat.com> writes:

> On Wed, Sep 2, 2026 at 6:58 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > On Tue, Sep 1, 2026 at 7:05 AM Markus Armbruster <armbru@redhat.com> wrote:
>> >>
>> >> Series
>> >> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>> >>
>> >
>> > Thank you for your suffering :)
>>
>> You're welcome; it's my job[*]!
>>
>> > So, I think there's actually no real problem in checking in a partial
>> > conversion as the infrastructure was coded specifically to allow it,
>> > however you're the maintainer so I will follow your lead. I'm more
>> > interested in moving forward than telling you how to do your job ;)
>> >
>> > The series will eventually enforce strict ordering, so there is no
>> > chance we will miss anything. If we send a PR now, we also don't have
>> > to keep rebasing the partial series against master. If you don't want
>> > to submit a PR, please create a branch I can track and submit patches
>> > against, and please periodically rebase it against origin/master.
>>
>> I worry a bit that having intros split about half between two styles
>> would cause confusion and friction.  I'd much prefer to get to >90%
>> fairly quickly.  If we think that's possible, I'm happy to queue up
>> things in my tree, and take care of the rebasing.
>
> Everything up until the "convert multi-paragraph intros" patch (#44 in
> my pending work) is approximately 87% of the total volume of
> conversions. In the most recent off-list mail I sent you, that's
> Sections 1-7 -- which is essentially all of the stuff that was
> factored out as "semi-trivial"/"simple", plus the "TODO" conversions.
> I believe these are pretty trivial to burn through, but would require
> a bit of dedicated time. We could probably do it in a week if we
> really pushed ...

Let's try!

> Existing volume of what you have reviewed and accepted is 55%.
>
> Well, either way, I just don't want to have to juggle so many patches
> in the interim, so I am pushing a bit to just merge it to make
> subsequent series easier to rebase and juggle so that e.g. I don't
> have to have increasingly long "based-on" tags.
>
> (Makes sad, pouting noises.)

I'm queuing up this series.

If the Based-on become too unwieldy for anyone involved, let me know.

>> [*] Some days my compensation is compensation for suffering ;)