mtcs's sandbox: docbook2book

This module transforms DocBook XML documents into Drupal books.

You can upload a valid DocBook document to a node, and the module transforms the XML content into a Drupal book. Chapters and sections turn into drupal nodes and they form the proper book hierarchy.

The module supports uploading images in ZIP format using the FileField Extract module.
MathML equations are also displayed if you browser supports that format (e.g. Firefox 6+, Chrome, etc.).

Requirements / installation

CCK, FileField and FileField Paths are required to install this module.

Download the DocBook XSLT software package and extract it into the module's directory.
Rename the extracted directory to docbook-xsl.

wget -q http://sourceforge.net/projects/docbook/files/docbook-xsl/1.76.1/docbook...
tar xzf docbook-xsl-1.76.1.tar.gz docbook-xsl-1.76.1/xhtml/
mv docbook-xsl-1.76.1 docbook-xsl
\rm docbook-xsl-1.76.1.tar.gz

Features / Limitations

• Source and target fields can be specified in the node edit form.
  You can specify the node body or any other textfields as output.
• The DocBook XML file can be replaced at any time. Activating the transformation again will update the book nodes based on the new version.
• There is only basic error handling. You have to follow the usage instructions very carefully (see below).
• The module uses the "chunker" XHTML output with lots of custom configuration options based on my experiences. Currently, there is no interface to override these options (you can always edit the code).
• The XSL transformation is done in one step. If your XML file is very large you might need to increase max_execution_time.
• Nodes are created in a batch process - this part will generate a lot of warnings.
• Child nodes will be created by duplicating the root node. This means that they inherit node type (and most of the node properties).
• Do not edit child nodes (content changes will be lost on DocBook XML update).
• Never ever edit child path aliases! The module identifies child nodes based on their path alias and book id.
• Images should be properly scaled before upload. ImageCache is not supported (since FileField Extract will not include files in the database).
• Transformation does not work on new nodes: the fieldsets don't appear until all requirements are met.
• ...

How to use it

The transformation can be activated in the node edit form by specifying the docbook XML source field, the target text field and (optionally) the filefield containing attached files in an archive.

1. Install and enable the module and all required software
   (Optionally) install and enable the Filefield Extract module.
2. Create a new input format (admin/settings/filters/add) (e.g. DocBook XML) and turn off all HTML filters except the HTML corrector.
3. Create a new content type (e.g. DocBook node)
   • Add a filefield (e.g. DocBook XML source) for storing the docbook XML file
   • Set the file path to something useful (e.g. docbooks/[nid]/xml).
   • Don't tick Required!
   • Disable file listing and enable DocBook import support.
   • (optionally) Add a filefield (e.g. DocBook files) to store attached files (disable listing, enable extract archive support and set the path)
4. Test your setup by creating a sample book (create Content: DocBook node)
   This will be the root node of the imported book.
   • Set title to anything (will be overwritten)
   • Leave the body empty
   • Set the input format to DocBook XML
   • Select "Create a new book"
   • Upload the DocBook XML file
   • (Optionally) upload the ZIP file containing all attachments
   • set the path to something useful (e.g. /books/sample/index). The ending has to be "index".
   • Save the node.
   • Edit the node again
     DocBook Import (and FileField Extract) fieldsets will appear this time.
   • Select the proper fields to activate the transformation (and extraction of archives)
   • Click Save and be patient if you have a large book

History

There were some attempts to handle a DocBook XML imports.
I was playing with Feeds to create a new importer. It is working but provides only a very basic support.
Book Import/Export is for Drupal 5.x and it does not yet support import.

Work in progress

This module is under development.
It will not tolerate configuration or input errors very well.
It does not modify your database tables (directly) so generally it is safe to use it.
Book delete module can be handy to delete complete books.