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.

   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.

-

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     | 448 ++++++++++++++-------------------------
 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        | 208 +++++++-----------
 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, 845 insertions(+), 1519 deletions(-)

-- 
2.55.0

John Snow <jsnow@redhat.com> writes:

> 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.
>
>    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.
> -
>
> 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.)

I checked whether the converted intros are indeed all "very trivial".
Only a few that aren't have crept in.  I replied to the patches.

I eye-balled whether these intros actually contain only introductory
text.  Looks like it (but I'm only human, and the checking is
t-e-d-i-o-u-s).  Many of them could use polish.  Not today.

With the few conversions that aren't "very trivial" dropped, series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

> 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.

Partial conversion is undesirable.  We need to finish the job.  We'll
need more than one series to have a chance at actually reviewing it.
I'm debating whether to keep them on a branch until we finish.

If I count correctly, roughly 70% of all intros are "very trivial".
Good to get them out of the way.

> 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?

Yes!