On Thu, Aug 27, 2026 at 9:39 AM Daniel P. Berrangé <[email protected]> wrote: > > On Thu, Aug 27, 2026 at 03:09:35PM +0200, Markus Armbruster wrote: > > Daniel P. Berrangé <[email protected]> writes: > > > > > On Wed, Aug 26, 2026 at 03:37:58PM -0400, John Snow wrote: > > >> Signed-off-by: John Snow <[email protected]> > > >> --- > > >> 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: <[email protected]> > > https://lore.kernel.org/qemu-devel/[email protected]/ > > > > 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.
In most cases, not very substantial. For commands and events, it *can* be quite a bit more substantial. For structs, enums, etc it is almost always laughably trivial. When the syntactical delineation of intro is complete, further QAPI parser changes will make it even more obvious: any free text that exists between the intro and the other sections will be flagged as an error, where you will be urged to move any detail text to below the metadata fields. This physical relocation will help suggest to the documentation author what goes "above the fold" and what goes "below the fold", so to speak. > > 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. Yeah, that's roughly the idea; and some prototypes used this idea in the past - but Markus wanted an explicit, obvious delineation precisely to *force* documentation authors to think about the split. It has implications for what gets generated into the documentation and in which scenarios. I do usually try to make my upgrades "invisible" to the user, but in this case I believe we are erring on the side of "explicit is better than implicit" because of the implications of the text not always being copied in a precisely straightforward manner to the HTML docs. I will address the subtleties of this issue when the inliner is being merged by updating a documentation writer's guide that covers what goes where and why. For now, we are just trying to do the bulk conversion. > > With regards, > Daniel --js
