OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: Am I using DocBook appropriately?




Tobias Reif wrote:
3E3E8F89.5000109@pinkjuice.com">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.
3E3E8F89.5000109@pinkjuice.com">

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.
3E3E8F89.5000109@pinkjuice.com">


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
3E3E8F89.5000109@pinkjuice.com">
Tobi





[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC