[Suggestion] : Section Numbering Schemes

[C. Michael Pilato]

Ramanathan Muthaiah wrote:
> Am not sure, if this has already been debated in the core group; but,
> I would like to put forward my suggestion:
> 
> Apart from chapter numbers, found in the svn book (v1.3), I do not
> find numbering schemes followed for major sections / subscetions.
> 
> Is there any reason not to have this style ?

Section numbers are a feature of the DocBook translation process, not of
the DocBook markup itself.  I prefer them remain disabled for a number
of reasons:

   * The book was originally composed as work destined for hardcopy,
     an O'Reilly publication.  O'Reilly doesn't use section numbering
     in its books.  In fact, I know of *no* publisher that uses
     section numbering in their books.

   * I've seen far too many documents with 6-level section numbers,
     and the eye is far too easily fooled into thinking that, at quick
     glance, 1.1.6.1.1.1 and 1.1.1.6.1.1 are the same number.

   * Our sections move around as we edit things, so their numbers would
     also change, and that's undesirable.

   * It isn't the default behavior for any of our output translations.

   * It reeks of Microsoft Word.  (Can't you smell it?)

The book has two target markets:  the Web (in which case folks pass
around URLs instead of chattering about "section 1.4.5.2 of the Book"),
and your bookshelf (where book versions and page numbers quite suffice
in terms of a coordinate system for identifying book content).

Of course, if you wish to generate the book in a format that has section
numbers, and that would better serve your purposes in some way, you are
more than welcome to do so!  It's just a tiny tweak to the XSL
parameters.  Attached is a patch that seems to work.

-- 
C. Michael Pilato <cmpilato at red-bean.com>

"The Christian ideal has not been tried and found wanting.  It has
 been found difficult; and left untried."  -- G. K. Chesterton
-------------- next part --------------
A non-text attachment was scrubbed...
Name: enable-section-numbers.patch
Type: text/x-patch
Size: 1218 bytes
Desc: not available
URL: <http://www.red-bean.com/pipermail/svnbook-dev/attachments/20070110/548adcfe/attachment-0001.bin>