Re: Manual toc depth

[Rocco Rutte <pdmef@xxxxxxx>]

Hi,

* Kyle Wheeler wrote:

> If I understand it correctly, in the XML, <sect2 id="abort-nosubject"> is 
> equivalent to \subsection{abort-nosubject} in LaTeX. The "right" solution 
> would be to describe config options using a more appropriate semantic 
> construct that correctly signifies the organizational importance of the 
> config options (such as putting them in an itemized list or something 
> similar) rather than simply asserting that sect2's are no longer 
> sufficiently important to be in the ToC. Isn't the real problem that 
> config options shouldn't define level-2 manual sections, rather than that 
> level-2 manual sections shouldn't be in the ToC?

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.

For me, sect2 is right, it's just that I can't exclude this specific 
chapter's sect2s from the toc. 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.

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.

> 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. I've also 
been thinking about this previously as I don't really like the section 
titles in chapter 3. E.g. a change I think I'd prefer would be:

  folder-hook: Setting variables based upon mailbox

But I don't know what do with sections where there're multiple commands, 
I think I don't like:

  reply-hook, send-hook, send2-hook: Change settings...

or what do that ignore/unignore command. I thought about restructuring 
chapter 3 to:

  - location of config files
  - syntax of config files
  - format strings
  - config commands
      - set/reset/unset/...
      - group
      - bind
      - ...

Ideas?

Regards, Rocco