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

[Michael Smith <smith@xml-doc.org>]

Hi Nancy,

Thanks very much for the reply on this.

You wrote:

> - 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 was thinking the same thing, but then did a little looking and
noticed that it's not so uncommon to see things other than books that
have appendixes. The W3C XML spec, for example, has several
appendices. So it seems like it might be useful to have Appendix
modularized outside of the book/set hierarchy, in case somebody wanted
to make (for example) a Specification hierarchy that included Appendix.

As far as the DTD goes, Appendix is actually is a valid child element
of Article (and Book and Set, but not anything else).

> - 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.

I've looked at existing help systems quite a bit, and it really does
seem that as far as the content modeling goes, all that anybody would
need to model the structure is a Helpset (or Project or whatever)
element with a child Topic element. But I think it's just a matter of
element names -- you can do exactly the same thing by using Book and
Chapter. In fact, I've written a customization layer that lets you use
Helpset and Topic for authoring, and a simple stylesheet that lets you
transform all your Helpset and Topic elements to Book and Chapter
elements so you can use the existing DocBook stylesheets to process
the transformed doc instances and generate HTML Help/Javahelp.

> - 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.

About the navigational components (ToC, LoT, Index) -- in practice,
aren't these sorts of things almost always automatically generated
during the processing stage, not manually authored?

If that's the case, no one needs the navigational components at all as
long as they're using a processing application (like the DocBook
stylesheets+ XSLT engine) that will generate all that navigation. The
only instance I can think of where I've actually used any of them is
in relation to the mechanism the stylesheets currently support for
generating an index -- you just put an empty <index/> tag into your
doc instance.

It seems like for help authoring, there's probably no more need for
navigational components than there is for print or HTML authoring --
it can be left up to the processing application.

So maybe the discussion of how to make DocBook more suitable for help
authoring will just turn into a discussion of what kinds of help
navigation stuff people are looking for, and what kind of processing
support could be created to generate that.

But even there, I guess I don't quite understand what the shortcomings
are, because using the standard DocBook stylesheets distribution, I
can already make HTML Help (with a generated TOC and index) from a
DocBook instance. And it seems like processing support could be built
for generating the same for any of the existing help formats/systems.

And again on the authoring side, other than adding something Helpset
and Topic, I can't really see what else we might do.

   --Mike


> 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