Neil Perlin

www.hyperword.com

When Microsoft announced in 1996 that the next version of Windows Help would be based on HTML rather than the older Rich Text Format (RTF), Blue Sky Software (eHelp's original name) began adding HTML support to RoboHelp. That support began as a plug-in that went through a sometimes tortuous evolution before becoming the powerful and largely stable authoring tool it is today.

We are now starting another shift—this time from HTML to XML. Once again, we're likely to go through a sometimes tortuous evolution before RoboHelp XML settles down.

This article is the first of a two-part series that examines Macromedia RoboHelp support for XML. Part 1 looks at the import and export features, while Part 2 will look at the "handlers." Both articles discuss the features' mechanics, their peculiarities, and some aspects of integrating them in a documentation workflow. These articles don't cover all the details but they will help you evaluate whether you can use RoboHelp in an XML environment.

XML support by RoboHelp X5 can be summed up in two significant points:

• RoboHelp X5 does not support native XML authoring. Instead, it imports several varieties of XML into RoboHelp—converting to HTML in the process—or exports HTML files to several varieties of XML. Exporting is fairly straightforward because RoboHelp exports files that it created. Importing is less predictable due to the vagaries of legacy material and peculiarities and changes in XML and RoboHelp.
• Because XML usage is fairly rare and still evolving in the RoboHelp community, the RoboHelp engineering team wasn't always able to define specific outputs. In those cases, RoboHelp doesn't create a finished and immediately usable output, like WebHelp does. Instead, it creates a set of files for additional, custom processing as needed. You'll see this in the "export a project to XHTML" option, for example.

After reading this article, continue reading the next part, RoboHelp X5 and XML – Part 2: Using Handlers to Customize RoboHelp XML Features.

Review of XML Concepts

If you are new to XML, you should read this recap of XML basic concepts. XML is similar to HTML in some basic ways:

• Each has files that contain content. HTML stores content in HTM files. XML stores content in XML or XHTML files, among other types.
• Each has syntax rules for the content. In HTML the rules are largely optional. In XML the rules are mandatory and defined in one of two forms. There's a basic set of rules that all XML files must follow to be well-formed. You can define more custom rules for specific industries or applications in a DTD (Document Type Definition) or schema. Files that follow these custom rules are called valid. Two documentation-oriented DTDs are DocBook and XHTML.
• Each has formatting rules for the content. In HTML these rules are defined in a CSS (Cascading Style Sheet) or sometimes, in a holdover from past practice, in the HTML files, otherwise known as "inline." In XML you must define the rules in a separate CSS or use the more powerful, but more complex, XSL (Extensible Style Language) that can convert XML material into other formats.

XML Exporting

This section discusses exporting to the predefined formats: DocBook or XHTML. Although you can export to other outputs, you'll have to create custom export handlers to do so (which I cover in Part 2).

To export, use the XML Output Options dialog box (see Figure 1). To open it, double-click the XML Output option under the Single Source Layouts folder on the Project tab.

Figure 1. XML Output Options dialog box

Figure 1 shows the dialog box and the predefined export handlers. If you select either DocBook option, the Advanced button becomes active. Clicking it opens the Advance Options dialog box (see Figure 2).

Figure 2. Advanced (DocBook Output) Options dialog box

Here's what the four handlers and the Advanced Options dialog box let you do:

• Export Project to DocBook (Content Only): Exports topics to XML files, creates separate files for any graphics, and creates XML files for the browse, index, TOC, see also, and glossary control files—plus a log file. This option does not export any DHTML or formatting data.
• Export Project to DocBook (Full-Featured Export): Similar to the previous option but also exports the project's CSS and DHTML JavaScript file, providing the full project in DocBook form. (You can open the topics in a browser but they won't be formatted, even though this option exported the CSS file. To display the topics with correct formatting, convert the DocBook to a viewable format, such as HTML, PDF, or PostScript.)
• Export Topics to DocBook (Content Only): Exports the topics, graphics, and summary log file.

• Export Topics to DocBook (Full-Featured Export): Similar to the previous option but also exports the project's CSS file and DHTML JavaScript file, providing all the topics in DocBook form. As with the Export Project to DocBook (Full-Featured Export) option, you must convert the topics to HTML, PDF, or PostScript in order for them to appear with correct formatting.

  Whichever DocBook option you choose depends on the files you need. For example, if you want to output the entire project for use online, you'd probably select the Export Project to DocBook (Full-Featured Export) option. If you want just the topics for PostScript, you'd probably select the Export Topics to DocBook (Content Only) option. Define which files you need and then try the options to find the appropriate one.

  Note: For more information about DocBook, see DocBook: The Definitive Guide by Norman Walsh and Leonard Muellner (O'Reilly & Associates, 1999) or read Writing Documentation Using DocBook: A Crash Course, suggested by Dave Beck of the Macromedia development group.

• Export Project to XHTML: Converts topics to XHTML with an HTM extension. (Note that this can cause trouble. See the note below about changing the extension and the discussion in the "XML Import" and "XHTML Filename Extensions" sections.) This option also exports the graphics, CSS, and JavaScript, and creates XML files for the browse, index, TOC, see also, and glossary control files—plus a log file.

  This option displays the topics properly formatted in a browser because it also exports the CSS file and adds the following reference in each topic's <head> section:

  <link rel="stylesheet" href="<nameofcss>.css" type="text/css" /> 

  If you open the HTML files in a text editor, such as Notepad, you'll see the reference to the CSS file and the namespace declaration for XHTML in the <html> tag.

  (Although the topics are formatted correctly when displayed in Microsoft Internet Explorer, the "start file" that this option creates does not open the output in the tri-pane window, as WebHelp does. This is because the Export Project to XHTML option is one of those open-ended outputs I mentioned in the introduction. It does not display a finished product, like WebHelp, but instead outputs a set of files for you to process further to create your finished product.)

  Note: You can change the XHTML file extension from HTM to another file extension by opening the XML Handler Manager to the Advanced page for the desired handler and changing the extension in the Export Topic File Extension field. (See the discussion about the XML filename extensions later in this article.)

• Export Topics to XHTML: Similar to the previous option but only exports the topics, graphics, CSS, JavaScript, and log file.

  The XHTML export option you use depends on the files you need. For example, if you want to output the project for use online, you'd likely select the Export Project to DocBook (Full-Featured Export) option and plan on additional processing. If you want just the topics for PostScript, you'd likely select the Export Topics to DocBook (Content Only) option.

XML Importing

This section discusses importing using the defaults. You can import other formats too, but you'll have to create custom import handlers to do so.

To import XML, use the Import XML: Select XML Import Handler dialog box (see Figure 3). To open it, select File > Import and select XML File.

Figure 3. Import XML: Select XML Import Handler dialog box

Figure 3 shows the dialog box and the predefined handlers. If you select the Import XML (CSS/XSL) option, the Advanced button becomes active. Clicking it displays the Advance XML Import Options dialog box (see Figure 4).

Figure 4. Advanced XML Import Options dialog box

The three handlers and the Advanced XML Import Options dialog box let you do the following:

• Import DocBook as Topics: This works well as long as the DocBook elements are correct and the DOCTYPE contains the right URI for the DTD. I once ran into a URI problem when I imported a sample DocBook file from FreeBSD with which to experiment. RoboHelp wouldn't import the file because it didn't have any URI for the DTD. I had to search the web for the proper URI. Once I found it and pasted it into the DOCTYPE specification, the file imported cleanly and without further problems. Just take this as a warning that demo files may not be as complete as you expect them to be.

• Import XHTML (*.xml): This feature can exhibit some peculiarities relating to the filename extension.

  The file type in the option name "…(*.xml)" changes depending on the XHTML file's extension. If the file has an XML extension, the option title reads "Import XHTML (*.xml)." If the file has an XHTML extension, the title changes to "Import XHTML (*.xhtml)." The extension does not change if the import file has an XHT extension because the predefined import handlers are not set up to recognize that extension. If you must import files with XHT extensions, you have three options:

  • Modify an existing handler to deal with files with the XHT extension. This is easy to do using the handler editor (covered in Part 2). The problem is that you lose the original handler.
  • Create a custom handler to deal with files with the XHT extension. This is easy to do using the handler editor. The problem is that you increase the number of import steps with each custom handler you create.
  • Change the XHT extension on any existing files to a different one and set up an internal standard for file extensions. I consider this option the best because it reduces the number of extensions and import handlers that you'll have to work with.

  Still, on the issue of extensions, because XHTML files can have HTM extensions, I once wanted to see if RoboHelp could distinguish between an XHTML file with an HTM extension and a regular HTML file. It didn't. Instead I was able to import an HTML file and an XHTML file, both with HTM extensions, by selecting File > Import > XML Import. This could be an issue if you think you're importing XHTML files with HTM extensions, only to discover that you imported a mix of HTML and XHTML files. This might prompt another standard that prohibits the use of HTM extensions for XHTML files.

• Import XML (CSS/XSL): Imports an XML file with an associated CSS or XSL style sheet. RoboHelp uses the CSS or XSL referenced in the XML file. If the XML file doesn't reference a CSS or XSL, you can specify one by selecting the Use Customized CSS/XSL File option in the Advanced XML Import Options dialog box and then choosing a CSS or XSL file. If you use this option, the Advanced button becomes active and you can select three options:

  • Treat as Text Flow: Imports the file as a topic with raw text and no formatting at all (see Figure 5). Use this option if you want to import existing material but want to eliminate the existing formatting and replace it with your own.

  • Treat as XML Tree View: Imports the file as a topic that, in Preview mode, acts like an XML file displayed in a browser. In other words, you can expand or collapse nested elements (see Figure 6).

    RoboHelp uses the <div> tag for the elements and marks them with grid lines. The lines don't appear when you preview the topic or generate the final output. Use this option if you want to see nested parent and child elements in a topic without having to preview it.

  • Use Customized CSS/XSL File: As noted earlier, use this option to import an XML file and assign a CSS or XSL file to it.

Figure 5. XML file imported as text flow

Figure 6. XML file imported as tree view

XHTML Filename Extensions

The Export Topics to XHTML option converts topics to XHTML with an HTM extension. Technically this is fine. However, it makes it impossible to distinguish by eye between HTML and XHTML files. It's also part of a larger question regarding which extension to use for XHTML files.

The W3C's (World Wide Web Consortium) XHTML recommendation does not specify which extension to use for XHTML files. This implies that HTM is an acceptable extension. However, as I noted above, this makes it impossible to look at a filename and know whether it is in HTML or XHTML format. This will cause confusion if your company has files in both formats; a better approach is to use XHTML as the extension.

In 2000 the IETF (Internet Engineering Task Force) recommended using XHTML or XHT extensions. The IETF recommended against using the XML extension because of the risk of confusion, at the server level, over how to distribute such files (text/XML or application/XML).

Finally, one website—whose address I've since lost and have not been able to find again—suggests using XTM as the XHTML file extension. I don't recommend this option because the XTM extension is for files in the Extensible Topic Map format.

Summary Observations

RoboHelp X5 does not support native XML authoring. It acts more like a format converter. This is good if you want to share files between RoboHelp and other projects. It's less optimal if you want to create XML files, however, because you must first convert the material. This can adds steps to the procedure and create problems such as incompatible or messy code. So whether you use RoboHelp for XML work depends on your documentation workflow.

Also consider whether that documentation workflow is based on one tool. In theory, any tool that creates XML or XHTML should create the same set of code, so tool standards should not be an issue.

In reality, you'll get different XML code depending on whether you create the XML using RoboHelp, Microsoft Word, or WebWorks Publisher for Word—just to name three tools. Each tool's output works in a browser, but the codes are different. These inconsistencies may cause odd behavior or conflicts that you may have to correct. For example, I once created a file in Word 2003, saved it as XML, and imported it into RoboHelp. When I previewed the topic, a subhead was superimposed on the title but the topic appeared correctly in the final output. I'm still not sure why this happened because the code looked right. To avoid this problem in a production environment, consider establishing some authoring tool standards in your company. (Enforcing those standards may be very difficult, especially if your company grows by acquisition or has a number of disparate documentation groups.)

You may also experience odd conversion results when working with files from subject-matter experts who create Word files with all text set in Normal style, or text applied with incorrect or irrationally chosen styles. I always suggest to clients who use a word processor like Microsoft Word that they train their subject-matter experts to apply styles correctly and make style usage a standard.

RoboHelp's XML support is new and still evolving. As you could expect in such a situation, its XML features are still evolving too. However, once you get past a few points of confusion, the mechanics of the features are fairly clear. I would describe the XML feature set in RoboHelp as a good first effort.

Continue reading the next part, RoboHelp X5 and XML – Part 2: Using Handlers to Customize RoboHelp XML Features.

Thanks to Dave Beck and Raul Ramos of Macromedia for their help with my questions.

About the author