Re: [docbook-apps] Element [...] not allowed in this context

[Juri Memmert <memmert@jpmdesign.net>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: RIPEMD160

Karen Schneider wrote:

Hi Karen,

> Yeah, the para wasn't even intended to be there (a n00b and her copy 
> of oXygen... what can I say). Thanks to Eric and Larry for quickly 
> responding.
> 
> This demonstrates also the importance of thinking through/planning 
> one's hierarchy. I can see it is possible to "run out" of hierarchy 
> (I haven't in this scenario, but I could see where it could quickly 
> happen).

I discussed the very idea of "running out of hierarchy" today. That
doesn't necessarily make my point of view relevant, only current. ;-)

Currently, one of my projects is in its planning phase. To properly
capture what the customer wants, the plan was to have a set of books,
each with a number of chapters. Each chapter containing a set of
sections and, inside these sections, recursive structures of even more
sections.

At this point in time, the innermost section has 11 parent sections all
the way up to its chapter, which is inside a book, which is inside its
set. So that is 14 levels of hierarchy in all.
As long as you're using <section> instead of numbered sections
(<sect1>...), that is, structurally, no problem at all. DocBook can
handle that easily.

Things are a little different when you look at how a DocBook document is
rendered (in HTML or XSL-FO or whatever). The current stylesheets render
everything down to a <sect5>, so you would have 7 levels of hierarchy
out of the box (5 sections inside a chapter inside a book). If that is
not sufficient (i.e. you ran out of hierarchy for your use case), such
as defining that, in a work on geography, a <sect1> is a section
describing a continent, a <sect2> described a country, <sect3> a
district, etc... Eventually, past <sect5>, the standard stylesheet will
run out of predetermined categories for sections. But you can add that
easily (see http://www.docbook.org/tdg5/en/html/ch05.html, "Adding
Elements: Adding a sect6").

So yes, the out-of-the-box stylesheet will not offer different
formatting for sections below the fifth recursive section. But a DocBook
document with 20 recursive sections will still be rendered, the last 16
section levels will, out of the box, just look identical concerning the
title layout. And if you need more, see the above link. ;-)

So no, in the context of chapters and sections, I do not see you running
out of hierarchy...




... Unless your problem is not a technical but a semantic problem (what
follows are some ramblings with little relevance to the above
statements, more on the topic of the semantics of DocBook tags than
anything else. Feel free to ignore.)

Assume a chapter to be a self-contained part of a book. Assume further
that a section is a part of a chapter but is not self-contained.
Then, a self-contained part of a chapter cannot be a section but would
be something like a sub-chapter, which does not exist in DocBook.
If you have such an element in your conceptualization of your book, then
yes, you run out of hierarchy because the current structure does not
lend itself to that decomposition.

If you change the definition slightly, however, it matches just fine.
Assume a chapter to be the top-most grouping in a book. Assume further
that all other groupings in a chapter are sections, regardless of
whether they are self-contained or not.
In this case, there is no semantic difference between a self-contained
section and a not self-contained section by its tag. If you wanted to
denote that difference, you would have to assign a role to these
sections and format them accordingly in your customization layer. But
you would never run out of hierarchy.

Maybe something to look into during your decision-making process.


With kind regards,

	Juri Memmert
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEAREDAAYFAkoIi8YACgkQeKE9NrxdrXwSYwCgnXGZdtygw7gKm5jT2tudn4B+
du4An0BRekeyJOKPMH+TIbyeTfOQAowG
=NTpB
-----END PGP SIGNATURE-----