Re: QAPIDoc Total Section Ordering

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Hi, let's recap...
>
> In general, it would be nice to have a strict inter-section ordering
> for a few reasons:
>
> (1) It makes it easier to add generated sections such as return
> values, undocumented members, or undocumented features/flags (such as
> Out-of-band execution), because there is a clear and obvious place
> where we should insert the generated doc. We have a few spots in the
> code now where we have a bespoke algorithm to find the correct
> insertion point, and it would be nice to consolidate this logic.
>
> (2) It makes the inliner easier, because merging two doc sections is
> more obvious when there is a normal order that must be adhered to;
> fields that are absent in one or the other docs list do not cause
> problems or complex edge cases.
>
> (3) It allows us to design around a unified look and layout in the
> HTML generator, which increases visual cohesion and yadda yadda yadda.
> In particular, each "group" of doc types is laid out in a block where
> having multiple fields of the same type be non-contiguous greatly
> increases visual clutter. i.e. all arguments should be contiguous, all
> features should be contiguous, etc. I have in the past referred to
> these groupings of doc section types as "doc regions".
>
> For these reasons, I'd like to nail down the order once and for all,
> and clarify a few things.
>
> The order I think you prefer is something like this:
>
> (1) Introduction ("Plain text", currently) - Always the first section,
> always precisely one section. (But may be multiple paragraphs housed
> within that single section.)
> (2) Arguments/members/values/alternatives
> (3) Return(s)
> (4) Error(s)
> (5) Feature(s)
> (6) Details ("Plain text", currently - generally used for clarifying
> detail, examples, and other information.)

  (7) Since

> Before I go any further, is this order "roughly correct" to you?

Yes!

> ...
>
> We previously discussed prohibiting "plain text" from appearing
> anywhere except in (1) or (6). From memory, the summary of that
> discussion is:
>
> Me: Prohibiting plaintext from appearing between 2-5 makes inlining
> easier, and improves HTML output by preventing plaintext paragraphs
> from interrupting the "tabular" output used to render metadata fields.
>
> You: Although it is not often utilized, we may want the freedom/power
> to use plaintext paragraphs to add addendums/notes attached to
> specific sections, i.e. adding a "Note:" to the tail of the arguments
> section specifically.
>
> I recall we debated this particular restriction quite a few times and
> at length; does this summary sound roughly accurate as far as you
> remember?

It does.

What breaks right now if you prohibit untagged sections between (2) to
(5)?