Re: Manual toc depth
Hi,
* Kyle Wheeler wrote:
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.
Well, the whole idea of DocBook and other markup languages nowadays is
to to separate content and layout. I think we should keep it that way to
ease possible future switches to other formats. Hacks such as bridgehead
could make the whole option docs render as sections though it's still
flat paragraphs (i.e. not something we want I think).
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.
Okay, so I'll look into how that works out.
How much work would it be to get it to generate an index?
Lots and lots of work basically, though chances are good that it can be
done mostly with regex replace. I think I once proposed introducing
another step in the processing chain using a custom XML dialect (which
was 99% DocBook + 1% mutt) so you can add these things for free.
I much prefer this:
<m:var name="mail-check"/>
over this:
<link linkend="mail-check">$link_check</link>
and with index:
<link linkend="mail-check">$link_check</link><indexterm><primary>Configuration
options</primary><secondary sortas="mail-check">$mail_check</secondary></indexterm>
DocBook is not very author friendly as you have type quite a lot for
even the most basic things things.
Regards, Rocco