Overview

The DocBookDocument product is a ZClass that provides rendering of DocBook Documents. It defines a new DocBook Document type based on XMLDocument and uses the XMLWidgets product for rendering.

This product is in very early development and is far from being able to render most DocBook documents. It should, however, be useful for short articles, how-to type documents, and FAQs.

It is based on an XMLDocument object with XMLWidget objects provided for rendering. The DocBookWidgets ZClass defines how a document is rendered. You may poke around there to see how each element is rendered and to add or modify support for other elements. The DocBookDocument ZClass provides a set of methods for viewing different types of documents.


Limitations

There are a number of limitations, some of which are listed below. There are probably many more.

*) Rendering of complex documents (documents with many nodes) is slow. This will hopefully be taken care of with a caching system in the near future. I believe this is mostly because XMLDocument is not very fast at traversing the node tree, but I could be wrong. 

*) Since DocBook is a large and complex DTD, most elements are not yet supported, and many never will be. Elements that are not supported are rendered by a default widget. This displays the XML source so you can see which parts of your document are not supported without having to go through the widget list. 

*) The id attribute is not supported. This is an XML Document product problem. 

*) Since the id attribute is not supported, elements that need it can not be supported (e.g., the <xref> element). This is a problem with the XML Document product and will hopefully be resolved soon. 
 
*) Although sub-sections of a document can be viewed using XML Document features such as /myDoc/e3/e42/view, the node IDs (e3 and e42 in this case) will likely change as the document itself changes. This causes a problem when bookmarking parts of a document. This is also a problem that should be resolved within the XML Document product. 


Supported Tags

For a listing of supported tags, view the xw_* objects in the DocBookWidgets ZClass. I may someday list all of them here and create sample documents to demonstrate how they are rendered. You can add support for new tags and modify how a tag is rendered by changing the render method of the xw_* widget objects.

Views

Currently only a default view (view) and a view book by chapter (view_book) are included. The default view renders the entire document on a single HTML page. The view book by chapter will display a DocBook <book> document that is divided into <chapter>s. It will first display a table of contents, with links to each chapter. Each chapter will be rendered on a single page with navigational links at the header and footer. You can modify these views to provide different navigational features or for other per page rendering needs.  The default view

If you access a DocBook document by its URL without specifying a view method, DocBookDocument will use the method specified by the default_view property of the document. If that property doesn't exist, the view method will be used.  


Comments

Despite its current limitations and youth, it should be useful for simple documents and easy to extend support for other elements. I'm especially interested in knowing if this is going in the right direction. There are a lot more elements to support and a lot more potential for navigational features. Please let me know if you have any questions, comments, suggestions, requests, widgets or anything else by sending e-mail to me at rbickers@logicetc.com. Thanks and enjoy!
