Re: [docbook-tc] Proposed modular hierarchy: diagrams, examples

["Nancy (Paisner) Harrison" <nancyh@rational.com>]

Michael,

Thanks for the proposal.  I think it's a good place to start as we consider updating DocBook to be more 'help=friendly'.  I do have a few omments:

- I'd keep appendix with the book hierarchy; I can't imagine using an appendix outside of a book, whereas I could easily imagine a glossary or bibliography that didn't apply to a specific book. Or are you thinking that an article might have its own appendix? (I have to admit that im my scheme of things, an article with an appendix would be a candidate for an appendectomy...)

- I think an additional helpset module is the right way to go in making DocBook more accessible out-of-the-box foto me is:
        - a root element (helpset?)
        - topic elements, probably with the same structure as chapter/appendix
Frankly, I can't think of any others except navigation (see below), since once you get past the topic level, the structure and content model is the same as for anything else.

- Navigation module: if we want to really support helpsets or webs, we need to define some new navigational elements, distinct from TOC, LOT, Index, etc. that are more suited to online information.  For example, they would need to be able to include different paths to the same leaf node.

I'm not yet sure whether a helpset module would be more useful to help authors if it contained all the necessary help structure (i.e. including the helpset navigation elements), or whether it would be better to keep all navigation together.  I think a discussion of pros and cons would be useful.

At any rate, thanks for getting us started on this.

Nancy



At 05:35 AM 10/11/01 , Michael Smith wrote:
>I put together a couple of diagrams showing how parts of the current
>hierarchy could be grouped into smaller modules.
>
>The first diagram is a modification of Figure 5-1 from page 93 of
>DocBook: The Definitive Guide.
>
>  http://www.logopoeia.com/docbook/modules_new.png
>
>The intent of that diagram is to show that all the actual hierarchical
>element definitions could be grouped into separate dbhier.*.mod files
>(e.g. dbhier.book.mod, dbhier.refentry.mod, etc.), which would
>basically leave the dbhier.mod file as a driver file.
>
>The second diagram shows one way in which the hierarchical elements
>could be grouped to form sub-modules.
>
>  http://www.logopoeia.com/docbook/hier_modules.png
>
>Here's text listing of the same groupings:
>
>  * sections module:        Section, Sect1-Sect5, Simplesect
>                         
>  * refentry module:        Refentry and its child hierarchy
>                         
>  * article  module:        Article (and Articleinfo)
>                         
>  * navigational         
>    components module:      ToC, LoT, Index
>                         
>  * supplemental         
>    components module:      Appendix, Glossary, Bibliography
>                         
>  * book and set module:    Book, Set, Part, Partintro, Reference,
>                            Preface, Chapter, Dedication, Colophon
>
>I also hacked the 4.1.2 distribution to show how this could actually
>be implemented. The modified distribution is at:
>
>  http://www.logopoeia.com/docbook/docbkx412_hier_mods.zip
>
>It doesn't change any content models in the DTD, so anything that'll
>validate against 4.1.2 will also validate against this modification.
>It just splits the hierarchy into separate files, like this:
>
>  dbhier.article.mod
>  dbhier.book.mod
>  dbhier.navi.mod
>  dbhier.refentry.mod
>  dbhier.sect.mod
>  dbhier.suppl.mod
>  dbhierx.mod
>
>The dbhier.*.mod naming convention is arbitrary -- it just seemed like
>the simplest name choice.
>
>If a DTD implementor wanted to restrict document authors to just
>authoring at (for example) the Section level, this modularization
>would allow him or her to do that with just a simple customization
>layer like this:
>
>  <!ENTITY % book.hier.module         "IGNORE">
>  <!ENTITY % article.hier.module      "IGNORE">
>  <!ENTITY % navi.hier.module         "IGNORE">
>  <!ENTITY % supplement.hier.module   "IGNORE">
>  <!ENTITY % refentry.hier.module     "IGNORE">
>
>  <!ENTITY % DocBookDTD
>    PUBLIC   "-//OASIS//DTD DocBook XML V4.2//EN"
>             "/usr/lib/xml/dtd/docbkx412/docbookx.dtd"
>  >
>  %DocBookDTD;
>
>I think that's a capability which'll be really useful to DTD
>implementors looking for an easy way to enable non-"book-oriented",
>more "modular" document authoring with DocBook.
>
>And it seems like a change that wouldn't cost us anything -- it think
>it'd 100% backward compatible.
>
>I reckon others have probably already considered doing some kind of
>further modularization of the DTD. Any comments on the approach to it
>that I've outlined here?
>
>  --Mike
>
>
>
>
>
>----------------------------------------------------------------
>To subscribe or unsubscribe from this elist use the subscription
>manager: <http://lists.oasis-open.org/ob/adm.pl>

________________________

Nancy (Paisner) Harrison

Rational Software

Lexington  MA

nancyh@rational.com