[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: DOCBOOK: A straw proposal for help topics in DocBook
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.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC