Singularity
In and amongst all my other work duties, I've been trying to develop a single-source XML based document publishing toolchain. A "solution", if you will, that will allow me to write documents in a layout-agnostic way based on document structure that can then be processed and published to whatever format I want or need: PDF, Microsoft Word, HTML, etc.
I'm surprised at the lack of integration and easy-to-use tools that seems to exist in the XML authoring world. I would have thought that by now, someone would have put together a package that approaches the sort of Microsoft Word/Corel WordPerfect model of authoring, but XML based, say with DocBook, but it doesn't seem to have been done. High-quality Windows-native XML editors with an authoring/publishing focus (as opposed to an IDE model) are rare, and I haven't found a free or open source editor yet that's reasonably feature complete. Once you have the editor, you still have to piece together an amazing amount of individual software and configuration details to put together a toolchain.
I got religion about XML for documentation recently, as I finished up a writing project I decided to do in LaTeX. I love TeX, LaTeX, and friends. I've been using them for years, know them well, and can get what I want out of them. What TeX provides, however, is a really powerful document-centric programming language for layout and typesetting, not for structure. LaTeX abstracts this a bit, but it's not perfect, nor is it intended to be. I'm a stickler when it comes to typography and layout in general, and especially in technical papers, so many of which are done in TeX without much attention to detail. At the same time, while I loved working in LaTeX during my part of the writing, it was abysmally painful to try and generate Word format copies of my paper that had anything near the same quality, which I had to do that so that my boss could read and edit the paper. I decided that structured documents really do make sense here, having had a first-person experience of never wanting to go through that again. XML and DocBook seemed to be easiest and most applicable solution to put into immediate practice.
And, from what it seems like, they still are. The problem is getting all the support software to work together. Initially, having also used FrameMaker for years, I tried to use its structured documents functionality to produce DocBook. I did some research on the 'Net and learned what problems people were having with XML in general and DocBook specifically in FrameMaker 7, which combines two previous products (FrameMaker+SGML for structured documents and FrameMaker for "classic" documents) into one, along with new XML support. While there are problems and bugs, they didn't seem insurmountable, and without going into too much detail, I started using it. I switched fairly early on not because it wasn't working, but because there was some associated clunkery, mostly due to known issues and Frame's outdated user interface (a user interface I already know pretty well, but outdated nonetheless).
Now I'm using Corel (formerly SoftQuad) XMetaL, and it's pretty good. My complaints with it are mostly around packaging. XMetaL Author is the straight XML-aware editor, XMetaL Developer is a package containing Author and Developer, where Developer is a plugin to Visual Studio .NET with sample projects, tools to build XMetaL rules files (compiled DTDs, essentially), and what not. The idea is that XMetaL Author goes out to the people on your writing/editing team who need to write and edit; XMetaL Developer is used by developers to customize XMetaL Author with scripts, macros, and new rules for new XML formats and deploy those to the Author users. For me, XMetaL Author is pointless without XMetaL Developer, since I plan to use more than just DocBook, and I plan to customize my DocBook use over time. DocBook isn't included with XMetaL, but I did manage to scrounge up a compiled DocBook "application" for XMetaL on the Web. A basic DocBook starter kit is included with FrameMaker 7.
For whatever it's worth, FrameMaker has similar issues, but it's all one product. FrameMaker doesn't natively work with XML, it works with its own concept of structured documents, which are validated against an EDD, or Element Definition Document, a sort of DTD for Frame. In order to use XML in Frame, you take your existing DTD and build an EDD out of it. You can then build an "application" which will manage the conversion during import and export to and from XML. It's this import and export process that's buggy with the included DocBook app, though you could feasibly extend and fix the app for your needs. FrameMaker has a long history of being a good SGML editor, so I'm a little surprised at the lack of clear documentation on how to use it with XML.
Aside from a sensible editor, there's the setup of the publishing toolchain. I was surprised at how little documentation I found for installing and chaining together various tools like XML parsers, XSLT engines, XSL-FO processors, etc. I was initially leaning to the relevant Apache tools: Xerces, Xalan, and FOP, but there was no clear way to find out how to string these together. I'm sure that with a little digging, trial and error, and a few pointed questions that I could get it all working, but therein is my point: I'm supposed to be writing documents. I could open up Word and be writing already!
My current setup, which is still subject to change, and is only "just enough and right now" to allow me to keep writing yet eke out some benefit of writing in DocBook includes XMetaL, DocBook XML, DocBook XSL stylesheets, and msxsl.exe, a command line tool that works with MSXML4 for XSLT processing.
I've skipped a lot of details and other tangents in this post for now because I'm very curious to hear from others who are struggling with a similar problem and their trials and solutions. Email me if this is something you're dealing with too!
Special thanks to Karl Schroeder, who very patiently and promptly answered many questions, steered me in the right direction, and continues to do so.
<< Home