John Snow <[email protected]> writes: > On Tue, Jun 9, 2026 at 9:39 AM Markus Armbruster <[email protected]> wrote: >> >> John Snow <[email protected]> writes: >> >> > Add parsing for explicit Intro section syntax. >> > >> > A side effect of this patch is that we will (currently) always create >> > an empty Intro section, similar to how we used to have an empty Plain >> > section. The tests are adjusted accordingly, rendered document output >> > does not change at all. >> > >> > Signed-off-by: John Snow <[email protected]> >> > --- >> > docs/devel/qapi-code-gen.rst | 16 +++++++--------- >> > scripts/qapi/parser.py | 4 ++-- >> > tests/qapi-schema/doc-good.out | 18 ++++++++++++++++++ >> > 3 files changed, 27 insertions(+), 11 deletions(-) >> > >> > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst >> > index 3a632b4a648..b1cc5b5f0db 100644 >> > --- a/docs/devel/qapi-code-gen.rst >> > +++ b/docs/devel/qapi-code-gen.rst >> > @@ -984,11 +984,11 @@ definition it documents. >> > When documentation is required (see pragma_ 'doc-required'), every >> > definition must have documentation. >> > >> > -Definition documentation starts with a line naming the definition, >> > -followed by an optional overview, a description of each argument (for >> > -commands and events), member (for structs and unions), branch (for >> > -alternates), or value (for enums), a description of each feature (if >> > -any), and finally optional tagged sections. >> > +Definition documentation starts with a description naming the >> > +definition with an optional indented overview, a description of each >> > +argument (for commands and events), member (for structs and unions), >> > +branch (for alternates), or value (for enums), a description of each >> > +feature (if any), and finally optional tagged sections. >> > >> > Descriptions start with '\@name:'. The description text must be >> > indented like this:: >> >> This works if we convert the entire schema in the same series. I guess >> that's the plan. Is it? > > I still plan to do it piecemeal: I will probably send everything out > in a big series, but you will be able to cherry-pick and stage those > patches individually as you feel they are ready. This way, modules > that need further revisions don't hold up the entire series and v2, > v3, etc won't email bomb all of creation just to fix an indent in a > single module somewhere.
We'll see. The important bit is separating "split the initial part into intro (to be discarded by the inliner) and non-intro (to be kept)" from purely mechanical "make the entire initial part syntactically intro". The transition to intro syntax will likely be bothersome for contributors, and I feel kind of bad about it. But I also feel we do need to make intro syntactically obvious. We could try to ease the pain by silently accepting old-style patches (not using intro syntax) for a while, then have another bulk conversion. > I think this documentation still covers it just fine: "an optional > indented overview". Technically the things we haven't converted just > omit that indented overview. Those overviews just remain as > "plaintext". You're right. "Optional" carries even more weight here than I thought. > It's not perfect documentation, but the expected window where we have > two competing systems should be quite small in the grand scheme, so I > don't think it's worth writing docs to cover the technicalities of the > transition. Okay. [...]
