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

[Lionel Mallet <l.mallet@xxxxxxxxxxxxx>]

First let me give you some information on my background which may illustrate 
my point.
Basically, I've been writing documents mainly using LaTeX, and later on 
FrameMaker. As you may know, in LaTeX, the sectioning commands are rather 
strict, and level and type are almost equivalent. LaTeX only merely imposes 
that sections inside chapters are numbered continuously. But you can overwrite 
that constraint by resetting the section numbering counter in your document.

On Thu, 17 Sep 1998 10:44:20 EDT, Norman Walsh <ndw@xxxxxxxxxx>  wrote:
> I was thinking of %component-numbering% (I really gotta lose that
> whole percent-thing someday) being either 'by-type or 'by-level Where
> 'by-type would imply what is done now and 'by-level would imply what
> you want.

OK.  That makes sense. And it looks like what you can do with LaTeX.

> My plan was to continue to ignore PARTs for the purpose of numbering.
> The fully general case where you could choose what levels of hierarchy
> to ignore would be fairly hairy and I'm not convinced it's worth it.
> Would you ever want not to ignore PART?  Is there anything else that
> you'd ever really want to ignore?

I think I now understand what you mean, that is: PARTs are not sectioning 
units but rather "structuring" ones (e.g., they could represent different 
volumes in a book).

To answer your question I think we have to look closely into the DocBook 
definition to see if any other element has the same semantics of "structure" 
vs. "section" (I hope I make myself understood, I'm not sure "structure" is 
the appropriate word for that concept).

> 
> | 2. it should be possible to specify the TOC format for a given level,
> |    whatever kind of element is inside
> |
> | 3. whether an element appears in the TOC and is numbered should only depend
> |    on its level in the document (maybe with additional filters
> |    on the type)
> 
> I don't like those requirements at all.  The kind of number an element
> gets should depend on it's type, not it's level, IMHO.  I don't think
> of a TOC as an outline.  I think this would just be wrong:
> 
>   I. Chapter 1
>   II. Chapter 2
>   III. Part 1
>      3. Chapter 3
>      4. Chapter 4
>   IV. Part 2
>      5. Chapter 5
>   VI. Chapter 6

Yeah. That's particularly odd!

> Likewise, I don't think I've ever seen this and don't feel any compelling
> need to support it, 'though I suppose I could be talked into it:
> 
>   I. Chapter 1
>   II. Chapter 2
>   III. Part 1
>      1. Chapter 1
>      2. Chapter 2
>   IV. Part 2
>      1. Chapter 1
>   VI. Chapter 6

That contradicts what you wrote above. If you replace your PARTs by 
REFERENCEs, 'by-level implies this numbering.

In fact most of our problems here come from the fact that DocBook is too loose 
a DTD. It allows almost any kind of structuring/sectioning command at almost 
any level (of course I'm exaggerating a bit;-). The fact that you can have 
chapters and parts at the same level is rather confusing for style-sheets 
developers (as illustrated by your example).

What I meant by my requirements is that if you select 'by-level, then the 
format of the number should be specified on a per-level basis. I wouldn't like 
to see things like:

A. Part
	1. Chapter
	II. Reference
	3. Chapter

On the other hand, if you select 'by-type, then you specify the format on a 
per-type basis. Like:

A. Part
	1. Chapter
	I. Reference
	2. Chapter

> I'm getting a sense for the problem space.
> 
> The features we want to control are:
> 
>   element numbering
>   element appearance in the TOC

Right. We are currently just discussing the first point.

> The conditions we can use for control are:
> 
>   element type
>   element level in the hierarchy
>   element ancestry

That last condition is where DocBook versatility hurts. And where the notion 
of level in the hierarchy helps a lot. There can be chapters at the same level 
as parts, or inside parts. So we cannot always use the element type as the 
only factor. Rather we have to let the document writer indicate how he wrote 
it.

>   level of the toc?  (a PART TOC vs. a CHAPTER TOC vs. a BOOK toc)
> 
> Does this extend to section numbering?  In the fully general case we could
> have even odder rules, like SECT1 in a CHAPTER in a PART in a PART TOC is
> numbered and a SECT1 in a CHAPTER in a BOOK is not.  I'd like to avoid
> going this far.

I agree. I would also like to avoid using the element ancestry in any case. 
Can you imagine the nightmare that would be to write the chapter-number 
function?

> I think I've just come to the conclusion that element numbering and
> appearance in the TOC are not merely orthogonal, they're unrelated.
> If it appears in the TOC it should be numbered if and only if it's
> numbered in the content.

That's definitely right. 

> I'm inclined to implement:
> 
>  - numbering based solely on element type
>  - the appearance of numbering based solely on element type

So you've dropped you 'by-level option:(

>  - appearance in the toc based on level + element type
> 
> How bad would that be?

I've just come to the conclusion that we're currently re-implementing LaTeX:-} 
But unfortunately, the grounds are far less clean:(

I hope I made myself clearer. In any case, this discussion is very interesting.
-- 
Lionel Mallet                           E-mail: l.mallet@xxxxxxxxxxxxx



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