In many cases, Help content is best delivered as HTML. For content authored in DITA, the process is typically to transform the content into HTML (or, more likely, XHTML), and then transfer the output files to a web browser. In some cases, it may be desirable to host the DITA source files on the web server, and use server-side processing to dynamically transform the content to HTML when a browser requests the information.
When DITA content is transformed to a delivery format through the DITA Open Toolkit or another publishing process, the result is a collection of deliverable files that also need to be managed. The deliverable files (typically XHTML) must be copied to a web server for delivery. When the source content changes, the output has to be regenerated, and then copied once more to the web server.
Most web servers support some sort of server-side processing technology; examples are ASP.Net, PHP and JSP. Many of these technologies are XML-aware, and are capable of handling dynamic XSL-T transformations.
It is possible to set up a system whereby Help content, written and stored in DITA format, is stored on a server, and then dynamically transformed into HTML for delivery.
To set up a dynamic transformation system, the services of a developer or someone familiar with a server-side processing and XSL-T is required. The developer will need to devise a menu system (perhaps derived from a ditamap file), and a topic rendering system.
Once the system is in place, DITA topics can be either authored directly onto the web server (perhaps through FTP, WebDAV, or a network share).
While it is relatively easy to set up a simple menu system and a simple topic rendering system, it is not easy to handle more advanced DITA features such as conrefs, reltables and composite topics. For example, conref elements need to be resolved prior to the XSL-T transformation. In the DITA Open Toolkit, the generation of output comprises a number of stages to first resolve references to build an interim document, and then process the interim document into the output.
However, if the DITA content is simple enough, this limitation is not an impediment.
The HyperWrite web site (http://www.hyperwrite.com/Articles/default.aspx) uses these techniques through ASP.Net to generate the breadcrumb trails, navigation system, menu pages, and articles topics from a ditamap file and numerous DITA concept topics. Some content topics are also hosted in DocBook format.
The primary advantage of the dynamic transformation approach is to minimize file management. The main disadvantage is that the technique is practically limited to simple content structures. Some other dedicated web delivery methods, such as Eclipse Help, Mark Logic Content Server, or other CMS solutions, provide greater support for complex content structures.
Tony Self
HyperWrite Pty. Ltd.
Chairperson, OASIS DITA Help Subcommittee