On Mon, Sep 28, 2026 at 10:33 AM Eric Blake <[email protected]> wrote: > > On Wed, Sep 23, 2026 at 11:17:58AM +0200, Markus Armbruster wrote: > > John Snow <[email protected]> writes: > > > > > Signed-off-by: John Snow <[email protected]> > > > > Consider mentioning how this affects rendered documentation: > > > > 1. blockdev-open-tray and blockdev-close-tray: first paragraph splits > > > > 2. block_set_io_throttle, nbd-server-add: Arguments: move up. > > I'm liking this series, but also the suggestions of documenting the > known impacts. At this point, I'm trusting Markus' review rather than > diving in deep myself, but you're welcome to add: > > Acked-by: Eric Blake <[email protected]>
I'll admit that I have been somewhat lacking in providing a comprehensive analysis in each cover letter as we have been doing this conversion rather piecemeal in order to make it more palatable on the list, but here's the best, shortest synopsis I can hope to give you: (A) In order to define a point in the documentation where we should insert auto-generated documentation (for members, returns, etc) we are pivoting towards a strict ordering of sections: 1. Intro 2. Members 3. Returns 4. Errors 5. Features 6. Details 7. Since With this goal in mind, the "Intro" will always be up at the very top, but "Details" - the unindented portions in this series - are ultimately fated to get sifted to the bottom. If you consult the rendered QMP documentation - for example `block-dirty-bitmap-add`: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html#command-QMP-block-core.block-dirty-bitmap-add The stuff that appears in the middle - Arguments and Errors - always forms a two-column table sort of layout. Anything that appears above it I have been calling "above the fold" - and that's always the Introduction text, now. Anything that appears below I have been informally calling "below the fold" - and that's always details text, now. So with this in mind, stuff I indent will go "above" and stuff I do not will go "below". Simple enough. (B) The tricky part: We are still pursuing the documentation inliner, which means that for block-dirty-bitmap-add, the arguments we "inherit" from the "BlockDirtyBitmap" structure will be displayed "inline" as if they were defined locally for this command. When we inline documentation from another definition/entity, we need to know where and how to splice the documentation together to form a coherent document. What Markus and I decided on was to *drop* the intro from any inlined documentation. For this reason, delineating the Intro from the Details becomes very important: the Intro text will not travel with the inlined arguments. With this in mind, the splits we are creating here become very important for structures specifically, as their intro text will get dropped on the floor when it is rendered in an inlined context. The split for commands, enums, etc., is less important because there is never any circumstance where we would drop the intro on the floor. > > -- > Eric Blake, Principal Software Engineer > Red Hat, Inc. > Virtualization: qemu.org | libguestfs.org >
