On Thursday, September 4 at 03:33 PM, quoth Rocco Rutte:
Well, I don't see a semantic construct that fits here (but I'm by far not a docbook expert). Sure, a list would do but that would look horrible for the hundreds of options. Everything that renders to something with indentation is bad I think.
Mmmaybe. But let's focus on fixing what's wrong in the correct sphere. sect2 may produce formatting you like, but has the ToC side-effect that you don't. There *has* to be a way to get decent formatting without forcing ourselves into a semantic mess.
But that's somewhat besides the point I think... which is whether it's user friendly to not have a list of options in the manual.
I think a list of options is useful.
E.g. when you want to look up some option's docs you would normally start searching from the beginning and hit it in the toc right away, click the link and get where you want. Without the options being in the toc, you have to skip probably lots of matches. Or search from the end backwards or type the append '#option' to the url... both not really user friendly.
I suppose they key with that would be to make the false-matches (at least, those that are the real name of an option) have a link to the real definition. Would that be sufficient?
In the "Configuration Commands" section of the manual, the various commands don't each get their own subsection, they're just part of a list (and thus don't show up in the ToC).A quick look suggests they all have their own section grouped by their meaning. The sections are just not named after the commands.
That makes some sense. Thinking about really good reference materials (such as the K&R C book), they often have a similar construction, with a good index for people who want to look up specific options or words. The ToC is more appropriately reserved for conceptual groupings.
How much work would it be to get it to generate an index? ~Kyle --We all grow up with the weight of history on us. Our ancestors dwell in the attics of our brains as they do in the spiraling chains of knowledge hidden in every cell of our bodies.
-- Shirley Abbott
Attachment:
pgprN60H2oxbD.pgp
Description: PGP signature