On Wednesday, September 3 at 09:31 PM, quoth Rocco Rutte:
I'd like to commit a change which makes the manual contain only chapters and sections in the manual to trim the table of contents, mainly to remove hundreds of sections for config options.Due to Brendan recalling objections I'd like to know what these are.The change (already backed out) would be identical to http://dev.mutt.org/hg/mutt/rev/e5610347fb3f.Are there any objections?
I don't recall objecting before, but it seems to me that this is solving the wrong problem. The real problem is that the config options shouldn't each have their own section. There are several level-2 sections (such as "editing-intro", "simple-patterns", and similar) that probably *ought* to be in the table of contents. I realize it would be a lot more work, but shouldn't the config options be more appropriately reformatted so they don't define their own sections?
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?
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). It seems to me that if this is appropriate for the long list of config *commands*, the same would be appropriate for config *options*.
At least, that makes sense in my head. :) ~Kyle --My fellow Americans, I'm pleased to tell you today that I've signed legislation that will outlaw Russia forever. We begin bombing in five minutes.
-- Ronald Reagan
Attachment:
pgpSed4n605Ly.pgp
Description: PGP signature