This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Am I using DocBook appropriately?
Tobias Reif wrote:
Jeff Biss
wrote:
Numbered sections permit a person to identify subsections
easier because of the hierarchical numbering.
That might go for the DocBook author, but not for the transformation tool.
And the reader of the generated presentational format (eg web, book) doesn't
care if the DocBook source utilized numbered or unnumbered sections AFAICS.
As I read the DocBook the numbered sections COULD
be numbered but don't have to be. If they are numbered then an obvious hierarchy
is generated. If they are not numbered then the converted output would look
like unnumbered sections.
I'm sure you've had problems figuring out where
in a book you were from the format of heading, numbering sections let's
a reader know where they are at all times.
AFAICS, that does depend on the output, not on the input. I mean, you are
describing features of the output, which could stay the same when switching
from numbered to unnumbered section elements.
Correct. But as I see it, selecting the correct
element at the time of writing will provide what you require at output. If
you select numbered sections at the start you can produce the output you
need, either numbered or unnumbered. If you use unnumbered at the start then
you have only the unnumbered output option, as set by your stylesheet.
Forget about trends and current styles
useage, use numbered sections where they help your reader.
But isn't that clearly the job of the transformer?
eg in XSLT, count(ancestor::section) will return the level, so the output
for
<section>
<section>
and
<sect1>
<sect2>
could be the same.
It could be the same. Again, as I read
it though, selecting numbered sections provide two options, with a corresponding
difficulty of maintaining the element hierarchy in the source. Whereas any
unnumbered section can be moved anywhere in the document, a numbered section
must be placed properly or you must change the element number depending on
where it is relocated and also ensure that the other numbered section tags
reflect the new hierarchy.
I could very well be wrong, but
deciding which element to use depends more on the potential output than anything
else. Unnumbered sections are easier to use because you don;t have to worry
about nesting whereas you must when tagging with numbered section.
I suppose one could use an ID with unnumbered
sections to produce numbering when the file is converted by a strylesheet.
This looks like it would be just as frustrating as using numbered sections
though.
Sincerely, Jeff Biss
Tobi