John Snow <[email protected]> writes: > On Wed, Sep 16, 2026 at 5:47 AM Markus Armbruster <[email protected]> wrote: >> >> John Snow <[email protected]> writes: >> >> > This patch converts some slightly-non-trivial intros with more than >> > one paragraph, but doesn't create any new intro/details splits. >> > >> > Review notes: The "See also ..." texts here are prime candidates for >> > moving into the details section with a ".. seealso::", but like the >> > last patch, as these are for enums and not candidates as an inline >> > source, I left them alone for now to keep patch sizes and motion down >> > until after initial review. >> > >> > Signed-off-by: John Snow <[email protected]> >> > --- >> > qapi/machine.json | 39 +++++++++++++++++++-------------------- >> > 1 file changed, 19 insertions(+), 20 deletions(-) >> > >> > diff --git a/qapi/machine.json b/qapi/machine.json >> > index 0516112f8e8..710b638b3bf 100644 >> > --- a/qapi/machine.json >> > +++ b/qapi/machine.json >> > @@ -608,12 +608,12 @@ >> > >> > ## >> > # @HmatLBMemoryHierarchy: >> > +# The memory hierarchy in the System Locality Latency and >> > +# Bandwidth Information Structure of HMAT (Heterogeneous Memory >> > +# Attribute Table) >> > # >> > -# The memory hierarchy in the System Locality Latency and Bandwidth >> > -# Information Structure of HMAT (Heterogeneous Memory Attribute Table) >> > -# >> > -# For more information about `HmatLBMemoryHierarchy`, see chapter >> > -# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec. >> > +# For more information about `HmatLBMemoryHierarchy`, see chapter >> > +# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec. >> >> This is one of the "see also" you discussed in the commit message. Such >> references tend to belong closer to the end, not in the intro. Moving >> involves a split. >> >> More of the same below. >> >> Not splitting now keeps the conversion simple, which is a plus. It >> reindents the entire unsplit intro, and if we do split it later, the >> part split off gets reindented right back. >> >> I'm happy to leave this decision to you. I'm adding to my notes on >> future work: >> >> 8. Move "see also" out of intro >> > > If you believe the ultimate destination for these is below the fold, > I'm happy to do it now. I just *didn't* because I wasn't entirely > sure. If you are, let's get it over with.
Having thought some more to reply to 2/9, I'd now draw the boundary like this: if we believe the ultimate destination is above the fold, make it intro, else keep it plain. This kicks less than easy contents decisions down the road to "eliminate plain sections after intro". Right now we need to get the syntax conversion done and merged. Doing plain section elimination incrementally is less bad than doing syntax conversion incrementally, I believe. Makes sense?
