Re: DOCBOOK: A straw proposal for help topics in DocBook

[Michael Smith <smith at xml-doc dot org>]

Nik Clayton <nik@freebsd.org> writes:

> [...]
> Didn't Mike Smith come up with a nifty way of remapping DocBook elements
> to other element names?

I wrote a simple XSLT stylesheet that 1)looks through a document for
any elements having an attribute with a certain name (which you
specify with an $attributename parameter) and then 2)replaces the names
of those elements with the value of the attributes. So it can be used
to remap elements to any DTD, not just DocBook -- you just change the
$attributename parameter. I'll post the stylesheet to docbook-apps.

The purpose of it is to allow you to author a document using any
arbitrary element names you want (like you describe below) then run
the stylesheet to transform them to standard DocBook elements before
processing. After the transformation you've just got a valid DocBook
document, so you can use all existing off-the-shelf DocBook processing
support-- the stylesheets, DocBook2X stuff, etc.-- to process it.

> IIRC, the rationale was that DocBook's sufficiently flexible that it can
> accommodate many different structures.  But people feel more comfortable
> writing:
> 
>     <help>
>       <topic> ... </>
>       <topic> ... </>
>       <topic> ... </>
>     </help>
> 
> (or whatever) than they do using
> 
>     <article>
>       <section> ... </>
>       <section> ... </>
>       <section> ... </>
>     </article>
> 
> Why not use that approach, instead of adding new elements to DocBook?

One reason might be that the help content models may not map
one-to-one to those of existing DocBook elements. The stylesheet
approach I was describing sorta assumes that you're just using the
standard DocBook content models, only with different names.

And I guess another reason is that many people want a 100 percent
off-the-shelf solution. Many DocBook implementors don't know how to
write a customization layer or don't want to. And as I think Ed Nixon
pointed out a while back, for promoting and evangelizing DocBook,
there's some value in having off-the-shelf support for authoring with
the kinds of element names that people expect to use for the type of
authoring they do. And there seems to be a big and growing demand now
for a set of online-help elements.

And keep in mind that if we added help content models, they could be
made optional -- added to the DTD in a modular way, so that they could
all be removed or "turned off" with a single parameter entity switch.
So if you didn't need or want them in your authoring DTD, you just
flip the switch and they're gone.

And we could actually do the same for all the other hierarchical
content models -- everything in the dbhier.mod file: all of the book
stuff, the navigational components, refentry hierarchy, etc. We could
further modularize the hierarchy by grouping parts of what's in
dbhier.mod now into sub-modules, in separate files, that could each be
included or ignored through use of parameter entity switches.

That'd make it easier for DTD implementors to mix and match or ignore
whatever building blocks from the hierarchy they choose. I think it
would be especially useful to DTD implementors looking for a way to
enable non-"book-oriented", more modular authoring with DocBook.

But getting back to the idea of enhancing the help-authoring support
in the DTD: After spending a lot of time thinking about and discussing
it, I think I have to say that I'd vote to do it. Having some optional
help elements would satisfy a lot of people, and I can't see that
they'd be redundant or add a lot of unnecessary complexity to the DTD.
All we need to do is decide on what the content models should be.




----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>