Re: [PATCH 1/4] docs: lift block-core.json rST header into parents

[Markus Armbruster]

Kevin Wolf <kwolf@redhat.com> writes:

> Am 09.09.2020 um 17:28 hat Markus Armbruster geschrieben:
>> Kevin Wolf <kwolf@redhat.com> writes:
>> 
>> > Am 09.09.2020 um 14:10 hat Markus Armbruster geschrieben:
>> >> Kevin Wolf <kwolf@redhat.com> writes:
[...]
>> >> > There are orders that I can't get this way.
>> >> 
>> >> You're right, ordering by first include is not completely general.
>> >> 
>> >> >                                             For example, if I want to
>> >> > have "Block devices" documented before "Background jobs", there is no
>> >> > way to add includes to actually get this order without having
>> >> > "Background jobs" as a subsection in "Block devices".
>> >> 
>> >> "Background jobs" is job.json.
>> >> 
>> >> "Block devices" is block.json, which includes block-core.json, which
>> >> includes job.json.
>> >> 
>> >> To be able to put "Block devices" first, you'd have to break the chain
>> >> from block.json to job.json.  Which might even be an improvement:
>> >> 
>> >> $ wc -l qapi/*.json | awk '$1 >= 1000 { print }'
>> >>   5527 qapi/block-core.json
>> >>   1722 qapi/migration.json
>> >>   1617 qapi/misc.json
>> >>   1180 qapi/ui.json
>> >>  17407 total
>> >> 
>> >> Could we split block-core.json into several cohesive parts?
>> >
>> > Possibly. However, while it would be an improvement generally speaking,
>> > how does this change the specific problem? All of the smaller files will
>> > be included by block.json (or whatever file provides the "Block devices"
>> > chapter in the documentation) and at least one of them will still have
>> > to include job.json.
>> 
>> Splitting block-core.json can help only if other modules then use less
>> than all the parts.  In particular, as long as block.json includes the
>> same stuff, it'll surely still include jobs.json.  Could it include
>> less?
>
> Not if the documentation wants to have a single chapter for the block
> layer instead of many small block related top-level chapters.
>
> Otherwise we could include some things directly from qapi-schema.json,
> but obviously, that would still have to be after job.json for some
> parts.

You're right.

Being unable to talk about something before you define it may not be all
bad, though :)