[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 1/4] docs: lift block-core.json rST header into parents
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 1/4] docs: lift block-core.json rST header into parents |
Date: |
Thu, 10 Sep 2020 07:18:24 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
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 :)
- [PATCH 0/4] docs: add qemu-storage-daemon documentation, Stefan Hajnoczi, 2020/09/08
- [PATCH 1/4] docs: lift block-core.json rST header into parents, Stefan Hajnoczi, 2020/09/08
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Laszlo Ersek, 2020/09/08
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/08
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Markus Armbruster, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Markus Armbruster, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Markus Armbruster, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents,
Markus Armbruster <=
- Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/10
Re: [PATCH 1/4] docs: lift block-core.json rST header into parents, Kevin Wolf, 2020/09/09
[PATCH 2/4] docs: generate qemu-storage-daemon-qmp-ref(7) man page, Stefan Hajnoczi, 2020/09/08
[PATCH 3/4] docs: add qemu-storage-daemon(1) man page, Stefan Hajnoczi, 2020/09/08
[PATCH 4/4] MAINTAINERS: add Kevin Wolf as storage daemon maintainer, Stefan Hajnoczi, 2020/09/08