Abstract
XML based structured documentation formats gain wider attention. But authors, editors and publishers of XML-based software documentations have to deal with many different XML-editors, content-management systems and publishing tools.
This article will propose the creation of an integrated documentation environment for authors and editors of XML-based documentation that will increase productivity and deployability of structured documentation environments.
I will show requirements of such an environment and software components that are already available to make up the foundation of a software documentation environment.
Table of Contents
XML is becoming more widely used for software documentation, because it offers among other points high flexibility, avoids vendor-lock-in and it is possible to create well customized solutions for documentation projects of virtually any size.
XML formats like DocBook or the Darwin Information Typing Architecture are designed for technical documentation and offer a high depth of semantic information. But there are a lot of other formats that are less complex and offer integrated processing tools, namely AurigaDoc or TBook.
Many companies use DocBook or customized version of it for their documentation needs, but it is not unusual to create a completely new XML-format for documentation. By using XSLT or other transformation technologies it is possible to transform one format into another without major problems.
The common actions associated with XML documents are creating, reviewing and publishing. Creating means writing the document and filling the text with markup to indicated structure and semantics of the written. This will be done using XML editors. The written text will be reviewed by editors in order to improve style and contents. For this task different tools can be used but, most editors will attach editorial notes to the draft version of the document.
For publishing, the transformation of XML in human readable formats like HTML for on-line help, PDF for printed manuals or Microsoft® HTML Help for operating system-integrated on-line help there is a wide range of tools available that will have to be put together in tool chains in oder to created the desired output formats.
There are two important fractions of XML editors. Source code based XML editors allow the author to edit the XML document directly and offer a high flexibility at the price of being often uncomfortable and the author will have to deal with source code and different constraints of XML documents like well-formedness and validity.
What You See Is What You Get (WYSIWYG) XML editors take a high level approach of presenting the document in a styled manner, assigning semantic information a visual representation. Most authors who are not programmers find this way of working easier and more productive as WYSIWYG editors will take care of keeping the document valid and well-formed.
Examples of good Source-based XML editors are XMLSpy™, jEdit and <oxygen /> XML™. The XMLmind XML editor™ and Syntext Serna™ a good and affordable WYSIWYG-editors.
In oder to quickly create draft versions of XML documents for an editor's review the document must be styled. XSL and CSS are standards that allow styling of XML documents.
Modern Web browsers like Microsoft Internet Explorer™ or Mozilla Firebird allow on-the-fly styling of XML documents through CSS and XSL. They are ideal for creating a quick draft output of the edited document.
The first step of transformation to be taken by a XML document is the transformation into a more presentation-oriented XML format like XHTML or XSL:FO. This transformation will be accomplished by XSLT processors. There are many XSLT processors available, among the most widely used are Saxon, xsltproc and the MSXML tool suite.
The next transformation step can be taken by XSL:FO-engines which will transform XSL:FO into PDF or PostScript for further printing. The most common tools are the free FOP and the commercial XSL:FO engines of RenderX™ and Antennahouse™.
Other transformation tools like the HTML Help Workshop of the Microsoft® Corporation will transform HTML into other formats.