Kevin Wolf <kw...@redhat.com> writes:
> Am 09.09.2020 um 17:28 hat Markus Armbruster geschrieben:
>> Kevin Wolf <kw...@redhat.com> writes:
>>
>> > Am 09.09.2020 um 14:10 hat Markus Armbruster geschrieben:
>> >> Kevin Wolf <kw...@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 :)
