Re: [PATCH v3 01/43] qapi: convert trivial intro sections for error.json

["Daniel P. Berrangé" <berrange@redhat.com>]

On Thu, Aug 27, 2026 at 03:09:35PM +0200, Markus Armbruster wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:
> 
> > On Wed, Aug 26, 2026 at 03:37:58PM -0400, John Snow wrote:
> >> Signed-off-by: John Snow <jsnow@redhat.com>
> >> ---
> >>  qapi/error.json | 3 +--
> >>  1 file changed, 1 insertion(+), 2 deletions(-)
> >> 
> >> diff --git a/qapi/error.json b/qapi/error.json
> >> index 54cb02fb880..a53b13e55c9 100644
> >> --- a/qapi/error.json
> >> +++ b/qapi/error.json
> >> @@ -9,8 +9,7 @@
> >>  
> >>  ##
> >>  # @QapiErrorClass:
> >> -#
> >> -# QEMU error classes
> >> +#     QEMU error classes
> >
> > Where is this need for indent coming from ?  From the POV of someone
> > writing comments, the need to indent the introductory text like this
> > feels very counter-intuitive, an exception from any other inline
> > docs syntax I've typically used. Is there any way we can avoid this ?
> 
> The cover letter explains the need:

Yes, I just didn't see the connection from that, to the use
of indent.

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

So IIUC, you're saying that we are going to rely on indentation
to distinguish introduction from details ?


> Note that the inliner elided Netdev's Intro "Captures the configuration
> of a network device."
> 
> However, when Intro and Details bleed together, the inliner elides more
> than it should.  I consider that a fairly serious issue.
> 
> I'm afraid forgetting to mark the end of Intro with "Details:" would be
> a common mistake, easy to miss in review.  So I explored possible
> alternatives:
> 
>     Subject: Re: [PATCH v2 00/10] qapi: enforce section ordering
>     Date: Wed, 15 Apr 2026 11:43:45 +0200
>     Message-ID: <87zf341ru6.fsf@pond.sub.org>
>     https://lore.kernel.org/qemu-devel/87zf341ru6.fsf@pond.sub.org/
> 
> John is working towards "3. Make the end of intro syntactically obvious"
> always, specifically "3c. Indent intro like descriptions and tagged
> sections" with the ultimate goal to reject unindented Intro.  That way,
> we cannot write an Intro with an unclear end.  John, correct me if I'm
> accidentally misrepresenting your work.
> 
> Questions?  Better ideas?

As an author, how substantive is "Intro" expected to be? I guess on
QAPI docs I've written I've not ever been aware of there even being
a distinct concept of Intro vs Details to think about. It is all just
some lines of prose to me.

My only alternative idea to indentation would be to declare that the
"Intro" is always the 1st paragraph of text and anything beyond that
is the "Details". That might match up with the way that contributors
naturally write text where the 1st paragraph conveys the key idea,
such that they dno't need to think about Intro vs Details as a
concept.

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|