Re: Numbering and TOC [was Re: Modular Docbook v1.13 bug]

[Norman Walsh <ndw@xxxxxxxxxx>]

/ Lionel Mallet <l.mallet@xxxxxxxxxxxxx> was heard to say:
| Basically, I've been writing documents mainly using LaTeX, and later on 

First, let me agree that DocBook is very loose.  For everyone
except a stylesheet writer trying to support all the
possibilities, this is probably a good thing.  If you want to
impose a particular, most strict, organization, you can do it
with a customization layer.  Because you're subsetting, you can
be confident that your documents are still "DocBook".

Next, let me appologize for rambling a bit in my preceding message.
(note to myself: "think first, then type". ;-)

Finally, let me outline what I've just implemented and how I think
what is in the stylesheets now gives you complete control with a
minimum of redefinition.

I wandered away from the 'by-type or 'by-level idea and instead
added these three functions:

  (define (component-number-restart-list cmp)
    ;; Return the list of elements at which numbering of 'cmp' should reset.
    ;; For example, for CHAPTER, it might return '("BOOK") causing chapters
    ;; to be sequentially numbered across a book.  If it returned
    ;; '("BOOK" "PART") then chapter numbering would restart at each 
    ;; BOOK or PART.

This function decides at what level of hierarchy the renumbering
of a particular component should occur.

  (define (component-number-ignore-list cmp)
    ;; Return the list of elements (inside the restart list) which are
    ;; hierarchy levels which should be ignored.  For example, for CHAPTER,
    ;; it might return '("PART") causing chapter numbering inside books
    ;; to ignore parts.
    ;;
    ;; Basically, if you skip up past a component/division element in
    ;; the restart list, you better put the element(s) you skipped in 
    ;; the ignore list or the stylesheet may never see your component
    ;; when it's trying to do the numbering.
  
This function decides what levels of hierarchy are "structuring"
rather than "sectioning" and are transparent essentially when it
comes to component numbering.

  (define (component-number-sibling-list cmp)
    ;; Return the list of elements with which 'cmp' should be numbered.
    ;; For example, for PART it might return '("PART" "REFERENCE") causing
    ;; sibling parts and references to be numbered together.
    ;; The gi of 'cmp' must always be in the list!

This function decides what elements are siblings.  Siblings are
numbered sequentially together.

I've also added a (label-number-format) function which decides
how the number of a component should be formatted.  This
function ultimately calls (appendix-lnf) to get the number
format for appendixes, (chapter-lnf) for chapters, etc., which
means you only have to redefine the single definition you want
to change, not the whole list. (I've done this for all the USEN
localization things and expect to do it for the other
localizations asap.)

I think the preceding functions plus these two observations
complete the picture:

- If you want to impose a particular label, you can with the LABEL
  attribute.  <chapter label="97"> will be chapter 97 no matter 
  where it occurs.

- If you want to special case the automatic numbering of a component,
  you need only redefine the [compoment]-autolabel function.  This
  function is passed the node that's being labeled, so it can look
  at the ancestry, siblings, children, whatever seems appropriate.

So the out-of-the-box stylesheets produce this:

I. Part
  1. Chapter
  I. Reference
  II. Reference

But with these definitions:

(define (chapter-label-number-format gind)    ;; gind is "gi or node"
  "I")

(define (chapter-number-sibling-list cmp)
  (list (gi cmp) (normalize "reference")))

(define (reference-number-sibling-list cmp)
  (list (gi cmp) (normalize "chapter")))

You would get this:

I. Part
  I. Chapter
  II. Reference
  III. Reference

I think I've covered all the bases, but please send me the
counter examples. ;-)

                                        Cheers,
                                          norm
-- 
Norman Walsh <ndw@xxxxxxxxxx>      | DNA neither cares nor knows. DNA
http://nwalsh.com/                 | just is. And we dance to its
                                   | music.--Richard Dawkins


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist