DocBook Projects

This section contains two downloadable DocBook projects. One is a structured FrameMaker 7.1 application that uses the DocBook XML 4.4 DTD. The other contains essentially the same XML but is formatted using the DocBook XSL stylesheets and a customization layer. Both projects can help beginners get started. I hope to work out the remaining bugs and I invite those who have solutions to send corrections.

The FrameMaker project includes the XML, graphics, formatting template, EDD, book file, book component files, rules file, and a structapps.fm file. The custom client is the one Adobe ships with its DocBook Starter Kit (docbook.dll). The XSL project contains the XML, graphics, customization layers (one for FOP and one for XEP), and two tiny scripts to control production under Unix/Linux/cygwin.

Structured FrameMaker 7.1 and DocBook XML 4.4

Frame_DocBook_example.zip

PDF using structured FrameMaker 7.1 and Acrobat Distiller

README from the Frame project

DocBook XSL and DocBook XML 4.4

XSL_DocBook_XML_example.tar.gz

PDF using FOP and xsltproc

PDF using XEP and xsltproc

XSL for FOP (contains comments and instructions, very messy)

XSL for XEP (modified from the FOP XSL, just as messy)

Compare and Contrast

Well, well, well, what a messy business it is formatting XML for print using an FO processor. If you've tried to format a book with FOP, even when using just a slightly sophisticated layout, I can't see how you would disagree. XEP does a much better job, good enough for professional output. But it's still quite difficult compared to using FrameMaker. And about setting up custom fonts for XEP on Windows, ouch! When using PostScript fonts with XEP, you need the AFM and PFA files for your font. A Unix/Linux system would be more likely to have the necessary files, or at least the scripts for producing them. On Windows, this is too much to ask.

But then, if an enterprise document production system is designed to minimize labor-intensive, error-prone, frustrating configuration and formatting, that's different. That means using fewer document formats. Write the XSL once, perfect it, and you have automated formatting. Very nice, but you have to put in the investment up front.

I found some problems with FrameMaker too. They are covered in detail in the FrameMaker project's README (and in my rant below). In short, FrameMaker is wonderful for producing books for print, but it imports and exports XML very poorly.

Based just on my limited experience, and at the risk of making everyone mad, I must say that neither the DocBook_XSL+libxml2+FOP or the DocBook_XSL+libxml2+XEP solution, nor the structured FrameMaker solution, is yet sufficiently perfected to enable relatively smooth, trouble-free use. Or, perhaps I should say that _I_ found them all to be painful. Establishing a professional document production system using structured FrameMaker, FOP, or XEP requires ascending a steep learning curve and/or the assistance of experts.

OK, . . . and there's also Arbortext Editor. It's quite good, but alone it doesn't format XML for any kind of output, and it requires special FOSI files just to format documents for its editing view. Without some output formatting solution and a solution for displaying documents on screen in a way that is at least close to WYSIWYG . . . , what can I say? GNU Emacs is a great editor too, and free.

[. . . cavalry charge bugle sounds . . .] Arbortext Styler to the rescue! Styler is easy to use and provides everything you need that Arbortext Editor lacks. With Arbortext Editor 5.1, Styler was an expensive add-on. With Arbortext Editor 5.2, some Styler functionality is provided with the default editor, specifically the ability to create "stylersheets" for editing view. When you open an XML file, the associated stylersheet is automatically translated to a FOSI for editing view. I used the full Styler product from Arbortext Editor 5.2 to produce a PDF of the same XML I used in the above downloadable projects. You can view that PDF → here. The Arbortext Editor 5.1 version of Styler did not fully support footnotes, and it had a nasty bug related to its element-relocation functionality. Those are both fixed in the Arbortext Editor 5.2 version of Styler. Styler is fantastic! However, my impression is that even now, years after Styler's initial release, very few people are using it. Most Arbortext customers still use FOSI, even for print.

I don't provide a downloadable Arbortext Editor project because I use a custom doctype in Arbortext Editor (DocBook XML 4.4) and there may be copyright complications with some custom doctype configuration files in Arbortext Editor. Besides, if you're creating custom doctypes in Arbortext Editor you aren't a beginner and you don't need my help; you should be helping me!!

<rant>
 FrameMaker's situation is complicated. Back around January and February of 2001, InfoWorld columnist Robert Cringley started somewhat of a buzz by writing in his column that he was receiving reports Adobe was laying off the entire FrameMaker development team (no longer available): http://www.infoworld.com/articles/op/xml/01/02/05/010205opcringely.html.

According to http://sunsite.lanet.lv/javafaq/ (no longer available), Adobe apparently responded with a press release in which they did not deny the layoffs. Later, Cringley wrote that Adobe denied the layoffs: http://www.itworld.com/App/817/IW010212opcringely/.

Not long thereafter, Adobe did indeed layoff the entire FrameMaker development team and outsource/offshore FrameMaker code maintenance to India: http://www.adobeindia.com. If you are considering a commitment to DocBook XML on FrameMaker, consider this fact in combination with the fact that the DocBook XML Starter Kit Adobe ships with FrameMaker 8.0 is essentially the same one they shipped over ten years ago as a DocBook SGML project in 1996/1997. Obviously, Adobe once had a commitment to supporting DocBook on FrameMaker, but that was long ago, and that commitment was for DocBook SGML, before DocBook XML even existed. The future of FrameMaker has been repeatedly discussed at length on the various tech writer, XML, and FrameMaker mailing lists and newsgroups. Links to a small portion of those discussions can be accessed via a google search. FrameMaker's future is continually in question, despite major and minor point releases, despite frequent patch updates, and despite Adobe's additional repackaging of FrameMaker in the "Adobe Technical Communication Suite".

FrameMaker has always had many very wonderful features, and version 8.0 shows that Adobe might now be committed to supporting XML via the DITA Starter Kit, the DITA application pack, the DITA menu, the DITA FDK client (ditafm_app.dll), and other DITA-related plugin dlls (ditafm.dll and ditabook.dll). Adobe is showing a level of support for DITA it never showed for DocBook XML. I expect Adobe is committed to continued DITA support. To slacken that support would be too expensive in that it would establish a pattern of supporting and then dropping support for XML DTDs/schemas. We may even see strengthened support for DocBook XML, but there is no reason for hope. If/when I need DITA, I may be very grateful! For now, I need better support for DocBook XML.

Structured FrameMaker is generally expensive, complicated, messy, deficient, and buggy. If you find it difficult to understand why I do not praise structured FrameMaker or if you think that I am being too hard on it, study the README file I supply with my downloadable structured FrameMaker project. Still, even after the release of version 8.0, all indications are that structured FrameMaker's core has not been actively developed for many years. I expect that the FrameMaker bugs exposed by DocBook XML are in structured FrameMaker's core code, not the unstructured code, and that fixing those bugs is just not worth it to Adobe. You can fix those bugs yourself, but probably not with read-write rules or import/export XSL. Fixing most of those bugs requires C programming and FDK clients used to override FrameMaker's default behavior. Nonetheless, even with FrameMaker as it ships in version 8.0, you can pretty much get exact formatting of DocBook XML if you are determined. If you are a C magician, you might get FrameMaker to do just about anything through the FrameMaker Developer's Kit and Structured FrameMaker API.

I have always liked unstructured FrameMaker very much, but structured FrameMaker may be suitable only for large organizations that require exact formatting and for those organizations that can recoup the required investments in custom API clients (FDK clients) and elaborate work-flow designs using XML pre-processing and/or post-processing. And, however unfortunate, because of structured FrameMaker's application design methodology, using it as it is will always be labor intensive.

The only reason I can find to recommend struggling with FrameMaker as a DocBook XML authoring system is if you wish to pamper your authors with WYSIWYG. Of course, you don't want them actually _doing_ any WYSIWYG formatting. Automating formatting tasks, and thus removing those tasks from authors' responsibilities, is usually one of the primary reasons for deploying an XML authoring system in the first place. So, introducing or retaining WYSIWYG authoring obviously can open or re-open a can of worms you certainly wish to avoid.

Nonetheless, like most authors I too usually prefer WYSIWYG authoring. Structured FrameMaker's WYSIWYG and page composition capabilities are very good, perhaps unbeatable, but these are capabilities that structured FrameMaker inherits from unstructured FrameMaker.

Although structured FrameMaker's bugs and deficiencies are numerous and severe, structured FrameMaker is not yet dead as an XML authoring/publishing system. Rather, it appears that structured FrameMaker has been seriously ill since sometime during Adobe's development of version 7.0 and has not yet fully recovered. It seems that structured FrameMaker has been mostly an animated corpse kept alive-looking by a cadre of authors, trainers, and consultants who charge real money to make excuses and/or implement fixes for structured FrameMaker's many bugs and deficiencies. Without the fixes (XML pre-processing before import, XML post-processing upon export, and "custom API clients" or "FDK clients"), structured FrameMaker makes a real mess out of valid DocBook XML. It doesn't just blow it upon import or export. Without some magic much stronger than that supplied with the DocBook Starter Kit's FDK client, structured FrameMaker creates invalid DocBook XML from valid DocBook XML at each stage: import, authoring, and export. I have no reason to expect it does any better with XML originally valid against any similarly complex DTD or schema, that is, at least not without the necessary FDK clients.
</rant>

With the DocBook_XSL+libxml2+FOP/XEP solution, you need not be a C magician, as is the case with the FrameMaker solution. But to have any reasonable degree of control when formatting DocBook XML with XSL, you need to write XSL code. The DocBook XSL stylesheets help a lot. Some parts of an XSL customization layer are easy to implement, but not all. Even though the DocBook XSL package includes automated formatting of TOCs, LOTs, LOFs, Indexes, etc., fine-tune page composition with XSL is generally difficult. FOP? FOP version 0.20.5 was buggy and deficient. FOP version 0.94 is much better, and FOP is under vigorously active development from an open-source community. Its future looks very good. XEP and the libxml2 tools work fine for me. As with FOP, the libxml2 tools have strong open-source development support. Most significant, when comparing the various solutions for authoring and publishing XML is the question of whether XML import/export translation is required. The FrameMaker solution requires it; the others do not. When editing operations are performed on an ASCII-based XML text file, avoiding the XML import/export problems that plague FrameMaker is easy. The cost is the loss of FrameMaker's WYSIWYG online display and its wonderful editing, book building, and PS/PDF features.