I refreshed my memory on this. It's been a while. Instead of replying
to your replies long after you wrote them, I'm going to write up my
thoughts in one place.
= General observations =
* We have three QAPI-generated manuals: QEMU QMP Reference Manual, QEMU
Storage Daemon QMP Reference Manual, QEMU Guest Agent Protocol
Reference.
* We generate an index for each manual: qapi-qmp-index.html,
qapi-qst-index.html, qapi-qga-index.html.
* The doc generator does not link to these indexes by itself. Instead,
each manual links to its index in its introduction section. This
makes the index really easy to miss. Even if you're aware, jumping to
the index is bothersome once this lone link is out of sight. Until
that changes, the practical value of improvements to the index is in
doubt. Doesn't mean improvements should not be made, only that they
better be cheap.
* You're proposing to additionally generate a "main" QAPI index
qapi-index.html for everything documented in any QAPI-generated
manual. Not linked from anywhere.
* Modules let developers structure the schema and the generated code.
They are not a thing at the QMP interface. Letting such internals
bleed into QMP documentation is *wrong*. The excuse for doing it
anyway is that the module tree is close to the section tree in
practice, and we can use the modules (which are readily available in
the doc generator) as an approximation for sections (which we don't
have there at this time).
= Indexes before the patch =
An index page starts with links
Alternates | Commands | Enums | Events | Modules | Objects | A | B | C | D
| E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X
| Y | Z
Then we have flat lists of the alternates, commands, enums, events,
modules, objects, entities starting with "A" or "a", ..., "Z" or "z".
Each list is alphabetically sorted.
The links at the top take you to the heading of the respective list.
The list entries link to entity documentation, except for "Modules",
which link to the beginning of the doc generated for a QAPI module.
The entries under "A", ..., "Z" have a (meta-type) suffix.
Every entity is listed twice, once under its meta-type (Alternates,
Commands, Enums, Events, Objects), and once under its first letter.
= Indexes after the patch =
An index page starts with links
By module | By type | A | B | C | D | E | F | G | H | I | J | K | L | M | N
| O | P | Q | R | S | T | U | V | W | X | Y | Z
Then a two level list module / entity name (meta-type) linking to the
entity's doc. Link "By module" takes you to its heading.
Then a two level list meta-type / entity name linking to the entity's
doc. Link "By type" takes you to its heading. This replaces the flat
lists Alternates, Commands, Enums, Events, Objects.
In both two level lists the outer level is collapsible.
Then flat lists "A", ..., "Z" as before.
Flat list "Modules" is gone.
The links at the top take you to the heading of the respective list.
Every entity is listed twice, once under its meta-type under "By type",
and once under its first letter.
The lists are now sorted case-insensitively.
= Critique =
Here's the one question that matters: what are readers trying to do when
they use the index page?
Assuming they find the index page in the first place (see "lone link"
under "General observations" above), but that issue is out of scope
here.
I believe readers use the index to jump to the doc for X, where X is
something they encountered in the QMP interface.
I don't think they'll use the index to jump to the doc of an Y they
encounter in documentation, because that Y will be a link.
X obviously includes commands and events.
I doubt it includes types. Type names are not a thing in the QMP
interface. You run into them only in documentation, but again, they are
links there.
We should make looking up a command / event as easy and quick as we can.
Let's examine how users can navigate to the index entry that takes them
to the command / event doc.
Before the patch:
1. Find the index page somehow (out of scope here).
2. Click on Commands / Events. For commands, can instead visually skip
over the alternates (which is just a few lines) to Commands.
3. Visually scan an alphabetically sorted list of ~250 commands (almost
seven screen-fulls for me) or ~50 events (a bit over one).
Alternatively:
2. Click on the letter the command / event starts with.
3. Visually scan an alphabetically sorted list of up to ~200 entries
(five screen-fulls for me).
Alternatively:
2. Have the browser search the index page for the name.
Alternatively:
1. Screw the index, search the entire manual (single page) for the name.
After the patch:
1. Same.
2. Click on "By type". If you can somehow divine that's where the
commands / events hide.
3. For commands, visually skip over the alternates (which is just a few
lines) to Command (could also collapse Alternate, but why bother).
For events, either scroll down a lot looking for the events, or
search for "event" (for me, that jumps right back to the top of the
page to show me the first event under "By modules"). Could also
collapse Alternate, Command, and Enum, but most likely just give up
and try an alternative.
4. As before, visually scan an alphabetically sorted list of ~250
commands (almost seven screen-fulls for me) or ~50 events (a bit over
one).
The alternatives are unaffected by the patch.
I'm afraid the patch makes the index harder to use.
Minor quibbles:
* The "type" in "By type" is wrong. It's by QAPI meta-type, which is
not the same as QAPI type. Casual readers will likely not be familiar
with the term "meta-type". Calling the thing type risks confusion
nevertheless.
* The Modules sub-index before the patch is useless. The navigation bar
on the left is much, much easier to use. It also shows the *actual*
section structure, not an approximation.
* The "By Modules" index after the patch is debatable.
* I can't see a use for the "main" QAPI index.
= Recommendations =
* Consider dropping types from the index entirely. This would make
navigating to commands and events via first letter links *much*
easier. No need for Commands and Events lists, the "A", ..., "Z"
suffice.
* Else, keep an obvious, one click path from top of index page to
commands and to events.
However, the list of commands is too long to quickly scan visually.
Consider breaking it up by first letter.
* Keep the switch to case-insensitive sorting.
* Definitely drop the Modules sub-index. I don't care for the "By
modules" thing, either. The navigation bar on the left does that job
better.
* Drop the "main" QAPI index.
* Out of scope for this patch: a manual's index page should be easy to
reach from anywhere in the manual.
Thoughts?
