DITA for Help

This article discusses the suitability of the DITA standard for creation and maintenance of Help content. In particular, it investigates whether DITA is a practical approach for authoring HTML Help for Windows applications.

By Tony Self

Isn't it obvious?

Can DITA be used as a Help authoring technology? Superficially, of course it can! The DITA Open Toolkit includes an HTML Help transformer, an Eclipse Help transformer, and an HTML transformer (which can also generate some sort of Table of Contents). So isn't it obvious then? DITA is perfect for Help authoring. Or is it?

Looking a bit deeper, it's not so obvious. Can I include context-hooks in my content? Can I specify a popup link? Can I build a modular Help system? If I can't, then DITA is probably not suitable for Help.

What is Help anyway?

Perhaps the first question we should have asked was "What is Help?".

Help is information, presented on-screen, that assists a user to use a piece of software to perform a task.

According to that definition, a PDF document can be Help, and a Word document can be Help. And a simple Web page can be Help.

When people refer to Help, however, they are typically thinking of a content arranged in a tri-pane design, with a navigation pane to the left of the content. And key to the navigation pane is the table of contents. Tri-pane Help is normally generated from a Help Authoring Tool, or "HAT".

Example of Tri-pane Help

In many cases, Help does its job (of assisting the user) better when it is context-sensitive. That means the Help opens automatically at the page most likely to assist the user, based on where the user is within the application. If the user is completing the Edit screen of a software application when she or he asks for Help, the information about the Edit screen will display in the Help window.

A Refined Question

A better question to ask about DITA and Help would be, "can DITA be used to create fully-functional, professional-looking, context-sensitive Help with a table of contents, index and full-text search in a tri-pane display?".

By fully-functional, we would mean that it contains the normal sorts of features found in a HAT-generated Help system, such as expanding text links, other DHTML, popups, graphics, multimedia content, and tables.

By professional-looking, we mean that it looks as though it was produced by a HAT-generated Help system, using cascading style sheets.

Feature List

What features are found in a HAT-generated Help system? There are obviously many possible features, but not all features are supported by all tools. Some years ago, Char James-Tanny devised a HAT Matrix, which provided a comprehesive comparison of tools and their features. Char's original spreadsheet has evolved into an interactive Web site at http://www.hatmatrix.com/.

The HAT Matrix suggests the following as features desirable in the output from a Help Authoring Tool.

• Context-sensitivity
• Secondary window links
• Rich text popups
• Breadcrumbs, browse sequences and related topic links
• Index
• Next/Previous links
• Table of Contents
• Glossary of Terms
• CSS
• Master Page
• Conditional content
• Full-text search
• A-Links and K-Links
• DHTML dropdown links and expansion links
• Standard hyperlinks to internal and external addresses
• Hypergraphics (image maps)
• Multimedia
• Modular Help
• Accessible output
• Standards compliant (W3C) HTML and CSS output

Of course there are many desirable authoring and content management features, but we are most concerned with the suitability of the Help output from DITA - not how we might create the DITA content in the first place! After all, one of the principles of DITA is separation of content from presentation.

Context-Sensitivity

This article by necessity will only concentrate on one form of tri-pane Help, that being Microsoft HTML Help, which still the most popular Help format. But it will be useful to first consider the fundamentals of context-sensitivity. In essence, context-sensitivity is the ability to specify a particular topic, within a collection of topics, to open. For compiled Help systems, such as WinHelp and HTML Help, where all the topics of a collection are zipped into a single document file, specifying a particular topic is not straightforward. By contrast, specifying a single HTML file in a collection of HTML files is straightforward, because every topic is its own file, with its own unique address or URL. (It becomes more complicated when we introduce a tri-pane frameset, but let's leave that aside for the moment.)

Context-sensitivity is a little bit more than just specifying a particular topic to open; there are also elements of window control. For example, we may want the Help window to open at a certain size, in a certain position, and for that window to be re-used when Help is called a second or subsequent time.

For Windows and HTML Help, a call to open Help context-sensitivity takes the following format.

 HtmlHelp(hwnd, 'fofp.chm', HH_HELP_CONTEXT, idh_OKButton)

Translated into English, the call passed a window handle (hwnd), the name of the Help file (in this case, fofp.chm), the opening method (in this case, HH_HELP_CONTEXT), and the context id of the topic to be opened (in this case, idh_OKButton). Different opening methods have different parameters. A method of HH_DISPLAY_TOPIC requires the HTML file name of the topic as a parameter, as in the example below.

 HtmlHelp(hwnd, 'fofp.chm', HH_DISPLAY_TOPIC, "abcde.htm")

A specific window definition can be specified by adding the window name to the Help file name, as in:

 HtmlHelp(hwnd, 'fofp.chm>mainwindow', HH_HELP_CONTEXT, idh_oview)

The challenge in using DITA for context-sensitivity will be specifying window definitions and context hooks in the DITA files.

Context Hooks

One way of looking at DITA architecture is to view it as a simple two level structure. There are topics, and topic maps (ditamaps). These components mirror HTML Help topic and HHC (contents) files. However, HTML Help also has a Project (HHP) file, in which the context hooks and window definitions are stored. Despite being stored in the project file (ie, at collection level), context hooks are architecturally at topic-level. They can be considered to be topic level metadata.

So does DITA have topic-level metadata to store context hooks in?

Topic-level metadata is stored in the <prolog> area of a DITA topic. Prolog can contain metadata such as the following:

• author
• audience
• brand
• category
• copyright information
• dates
• keywords
• permissions
• platform
• product information
• publisher
• revision information.

The metadata most appropriate for context hooks is <resourceid>. The DITA Language Guide suggests its use as follows.

The <resourceid> element provides an identifier for applications that require them in a particular format, when the normal id attribute of the topic can't be used. Each resourceid entry should be unique. It is one of the metadata elements that can be included within the prolog of a topic, along with document tracking and product information, etc. The element has no content, but takes an id attribute and an appname attribute.

We could indeed use this element to store a context string, as in the example below.

<resourceid id="idh_OKButton" appname="htmlhelp" />

However, context hooks are made up of a string and a number, as in:

#define idh_OKButton 1001234

Without the number component of the hook, the context hook won't work. We have to keep looking for a suitable metadata element.

The answer may be in the <othermeta> element. Our context hook could be described using two of those elements, as:

<othermeta name="contextstring" content="idh_OKButton" />
<othermeta name="contextnumber" content="1001234" /> 

It's not elegant, but we can store the context hook metadata we need to store.

Map Files and Alias Strings

Having somewhere to store the context hooks is one thing. Generating those hooks into a format used within the Help compiling process is another. So, how does the HTML Help process context hooks?

In HTML Help, map files associate context numbers and context strings, while alias strings associate context strings with topic file names.

Context numbers and strings can either be included as lines in the [Map] section of the HHP file, or in an externally referenced file. Alias strings can either be included as lines in the [Alias] section of the HHP file, or in an externally referenced file.

The creation of an XSL transformation file to process the ditamap file to produce HTML Help map and alias files from the <othermeta> elements is actually a relatively easy task. Over time, we could expect the DITA Open Toolkit to include such a transformation file, but there is currently no such XSL file! It is fair to say that standard DITA tools don't currently provide a means for creating map and alias files used by Help compilers, but may soon do so.

Project File

If the principal differences between a CHM file and context-sensitive CHM file are window definitions and context hooks. If DITA to be used as a practical context-sensitive Help authoring environment, it must be able to cope with context hooks, and it should be able to deal with window definitions. In HTML Help, both of these features are managed in the project (HHP) file.

At a technical level, the ditamap file must be able to transformed into a map file referenced from the HHP file, alias strings in the HHP file. It must also be possible to direct, during the transformation process, window definitions to be added to the HHP file.

Let's look at how the DITA Open Toolkit utilities transform DITA into HTML Help.

• The HHP file is generated from the ditamap file by map2hhp.xsl.
• The HHC file is generated from the ditamap file by map2hhc.xsl.
• The HTML files are generated by a number of XSL files in a series of processing passes.
• The HHK file is generated during XSL processing of the topic files.

The HHP file is a simple text file, and the map2hhp transformer is a simple XSL file. It is a simple job to modify map2hhp.xsl to nominate a context hook map file, add alias strings, and to define windows.

It is likewise a relatively simple process to create another XSL file to process the ditamap and generate the context hook map file.

Window Definitions

In the HTML Help environment, a context-sensitive Help call can nominate a window name as well as the topic to open. Definitions (or configurations) for named windows are normally defined in the HTML Help project file, and include settings such as window behaviour, size and position, menu and toolbar visibility, and contents and index files to display.

Window definitions can be viewed as collection-level metadata. The logical place to store HTML Help window descriptions is in the ditamap file. The main purpose of a ditamap file is to bind or associate a group of individual topic files into a book, document or collection. The ditamap can contain very little collection-level metadata, and there are no suitable containers for storing window definitions.

Without a suitable container for window definitions in DITA, we may have to accept that windowing functionality is limited.

Secondary Windows

It is often important to display linked information in a new window. The reason for these secondary window links might be to differentiate core from supplementary information, or it could be to allow the user to temporarily branch to see additional information without leaving the main navigation path. And there are many other reasons, including the need to differentiate the main content from externally-provided information, such as when linking to a third-party Web site source.

In HTML, secondary window links can be defined in HTML code (by including a target attribute in the anchor tag) or through JavaScript (which affords greater control over the characteristics of the secondary window).

In DITA, the <xref> element is used for cross-referencing, but there is no specific attribute for specifying a target window name for HTML output, nor for specifying a JavaScript command. However, there is a scope attribute, the semantic purpose of which is to identify cross-references to topics within the current information set (local), or topics outside the information set (external). By default, most processors will generate external links as secondary window links (using the HTML target method).

Sample External Link to External Web Site

Sample Local Link to External Web Site

So links to secondary windows are possible in DITA, but defining how those windows should appear (size, position, button and menu configuration, etc), is not possible.

If DITA were to allow us to use HTML Help secondary windows, or HTML secondary windows invoked by JavaScript, how would it work? Firstly, we would need another attribute in the xref element to nominate the name of the window definition to be used to display the target topic. Then we would need somewhere to store the settings and configuration of that window definition.

But without a place to store those settings, again we may have to accept that secondary window functionality is limited. (We could also look for some post-processing workarounds, but that's not an ideal alternative.)

Popups

A popup window, in Help terminology, is a small borderless windows displayed over the currently displayed topic, showing a small snippet of explanatory information, and where the popup window disappears when the user clicks elsewhere on the screen. Popups are often used to display definitions of terms. Most Help Authoring Tools use DHTML to achieve the popup window effect. DITA has no capacity for specifying popup information.

Popups can be thought of as specialised secondary windows, and it is possible to modify the behaviour of a secondary window link invoked by JavaScript to create a popup-like behaviour. When DITA supports secondary window definitions, it will also fortuitously support popup functionality.

Breadcrumbs, Browse Sequences and Related Topic Links

Breadcrumbs and browse sequence are essentially navigation links based on associations between topics. In DITA, the ditamap file contains a relationship table (<reltable>) element, which defines intricate relationships between topics in a collection. The standard DITA Open Toolkit tranformation to HTML (and HTML Help) converts relationship table information to hyperlinks. With some clever DHTML, these links can be converted into more aesthetic (or familiar) breadcrumbs.

Index

HTML Help stores index entries, and the topics they are associated with, in a project-level HHK file. Logically, index entries are topic-level elements, and that's how DITA treats them. Index entries are defined in DITA by inserting <indexterm> elements within the body of a topic. DITA indexes transform losslessly into HTML Help indexes.

Next/Previous Links

Next and Previous toolbar buttons in HTML Help are a function of the HH viewer program, and are enabled by a flag setting in the project (HHP) file. DITA does not have the equivalent of an HHP file, so it cannot control the Next/Previous flag. However, a workaround to this might be possible at the transformation stage, when the DITA Open Toolkit process generates an HHP file. (See Project File.)

Table of Contents

The HTML Help Table of Contents (HHC) file closely parallels DITA's ditamap file, and is created by the standard DITA Open Toolkit transformation.

Glossary of Terms

Some Help Authoring Tools, notably RoboHelp HTML, provide a mechanism for generating a glossary of terms which displays in the navigation pane. This is not a standard HTML Help feature, but a third-party add-on. As such, DITA can't produce a glossary in that form. However, DITA does provide for storage of glossary terms through the <term> element, and such terms can be output into a glossary topic.

CSS

The DITA Open Toolkit transformation allows you to specify a CSS file to be attached to all the HTML topics generated from the DITA source topics. CSS classes can also be specified within most DITA element attributes, and this effectively provides an expansive range of CSS opportunities in HTML and HTML Help output.

Master Pages or Page Templates

To a certain extent, master pages or page templates are made redundant by separation of the content and presentation layers when using DITA. Some Help Authoring Tools permit different page templates for different sections of the one document, allowing a different look-and-feel for each section.

During the transformation of DITA to HTML, a nominated cascading style sheet can be applied to all generated topics, but not different style sheets for different sections.

It's hard to know how desirable such a feature is, but if necessary, it could be partially replicated in DITA by applying an output class to the <section> or <body> element of like topics. For example, if all topics relating to overview topics were to be displayed with a different heading and background colour to other topics, an outputclass of "overview" could be added to the <conbody> elements of those topics. On transformation, the outputclass would become a standard CSS class in the HTML output. The CSS file could direct elements within the HTML with that class to be displayed with a different background colour.

A better philosophy to adapt would be to use semantic markup to identify why topics need to be displayed differently. For example, perhaps all Concept topic types should be displayed differently, in which case the XSL files could be easily modified to process those topics differently during transformation.

Conditional Content

DITA has powerful conditional content attributes throughout and throughin, and is extremely capable in this area. Maps, topics, sections, paragraphs and inline elements all provide a wide, and expandable, range of conditional metadata, covering attributes such as language, version, product, platform, revision, status and importance. It also provides open-ended otherprops attributes for further condition markup.

Full Text Search

Full Text Search in HTML Help is a function of the HH viewer program, and is enabled by a flag setting in the project (HHP) file. DITA does not have the equivalent of an HHP file, so it cannot control the Full Text Search flag. However, a workaround to this might be possible at the tranformation stage, when the DITA Open Toolkit process generates an HHP file. (See Project File.)

A-Links and K-Links

The DITA approach to linking related topics is quite different from the HTML Help approach. In HTML Help, the index can be used as a basis for linking, where a link control can be used to link to, say, all topics with an index of "bird". These are known as K-Links. Separate to the index in HTML Help is an associative keyword index, which is essentially an index with no user interface, or an invisible index. HTML Help link controls can also be used to link to all topics with a common associative index. These types of links are known as A-Links.

DITA's approach is to store relationships between topics not in an index, but in relationship tables within the ditamap. DITA also takes a harder line when it comes to topic-based content, where specific links inline within the content are discouraged. The reason for this is that a topic may be re-used in different contexts by different ditamaps. The topic may be a page in a new user training guide, but may also be a page in an administration guide. The links required when the topic is within the training guide context are likely to be different from those in the administration guide context. But those different relationships can be separately specified in the relationship tables within the different ditamap (one ditamap for the training guide, and another for the administration guide), and links based on those relationships can be specified within topics.

The nub of it is that DITA does not support A-Links or K-Links, but DITA reftabls, and other link elements (such as <linkpool>), provides equivalent functionality within a different conceptual paradigm.

DHTML Dropdown and Expansion Links

DHTML dropdown and expansion links are technically possible by using the outputclass attributes on those elements within the topic that are going to display and disappear, and writing custom JavaScript code to include on each output HTML topic. However, this is not an easy endeavour. More importantly, it is at odds with the DITA philosophy of separating content from format and display. If such an idea (of using outputclasses and JavaScript) was adopted within a DITA-based documentation project, it is easy to see the productivity benefits of using DITA disappearing as writers become bogged down trying to get display features working.

In short, use of DHTML dropdown and expansion links is not practical. (However, the addition of an onclick attribute in the <xref> element may provide a building block for the transformation process to be customised to allow some DHTML in the ouput.)

Standard Hyperlinks

Hyperlinks are, of course, a delivery-specific term. (Paper books can't have hyperlinks.) Being a content storage format only, DITA doesn't suport hyperlinks as such, but does have cross-reference elements. And when transformed to online media, the cross-reference elements become hyperlinks. The DITA <xref> element provides elementary support for relative and absolute hyperlinking to other DITA topics, bookmarks within DITA topics, external files (such as PDFs), and external Web sites.

Hypergraphics

DITA has an <imagemap> element, which supports the basic functionality of the HTML "client-side" image map markup. When output as HTML or HTML Help, the DITA imagemap converts to the HTML equivalent, allowing you to designate a linkable area or region over an image. It is up to the DITA authoring tool to provide a user interface for the creation of the imagemap information.

Multimedia

DITA copes well with inclusion of Java and Flash objects. The <object> element in DITA is in essence a replica of the <object> tag in HTML. This effectively means that any media object that can be included in HTML can be included in DITA.

Modular Help

Although the DITA ditamap structure allows for modularity (ie, ditamaps referenced from ditamaps), the standard DITA Open Toolkit don't translate modular structures into modular HTML Help (or Eclipse Help, for that matter) structures. The standard transforms simply flatten the master and embedded TOCs into a single HHC file.

However, it is technically possible to modify that standard Open Toolkit files so that they do produce truly modular HTML Help output files.

Accessible Output

DITA markup includes solid provision for accessibility, such as alternative text attributes, throughout its elements.

Standards Compliant

The standard DITA Open Toolkit transformation to HTML and HTML Help can generate standards-compliant XHTML output without fuss.

Workarounds

A powerful feature of the DITA Open Toolkit, rather than DITA itself, is the build file. It is used during the process of transforming DITA content to delivery formats, including HTML and HTML Help. For HTML Help output, it permits the specification of a header and footer block in the body section of the topic's HTML, and the specification of HTML code to be included in the head section of each topic's HTML. Being able to add code in the head section means that an external JavaScript file can be referenced (allowing custom DHTML in the output). The build file also permits specification of a include file, which is a simple text file listing other support files to be compiled into the HTML Help CHM file. A JavaScript file referenced in the head section can thus be compiled into the CHM.

Context-sensitive Help map and alias header files can also be specified to be compiled into the CHM in the same way. These features open the door to many opportunities for enhancing the functionality of the output Help file. But good knowledge of JavaScript and DHTML is required to bring it all together. Once developed, however, the process can be systematised, so that the functionality can be replicated across many projects.

Summary

Table:

Help Feature	Current DITA Support for that Feature	Possibility of Future DITA Support
Context-sensitivity	Limited support, but possible with post-processing	New metadata required at ditamap level. New DITA OT transformer required.
Window definitions	No support	New metadata required at ditamap level.
Secondary windows and popups	Limited support (scope element)	New metadata required at ditamap level. New attribute in xref element.
Breadcrumbs	Good.
Index	Good.
Next/Previous links	Some.	Custom XSL or DITA OT improvements.
Table of contents	Good.
Glossary of terms	Some.	Custom XSL or DITA OT improvements would add opportunities.
CSS	Good.
Master page	None. Difference in philosophy.
Conditional content	Good.
Full-text search	Provided by output platform.	DITA OT improvements.
A-Links and K-Links	None. Difference in philosophy.
DHTML links	None.	New attribute in xref element.
Hyperlinks	Good.
Multimedia	Good.
Hypergraphics	Some.
Modular Help	Limited.	DITA OT improvements would add opportunities.
Accessible output	Good.
Standards-compliant	Good.

Conclusion

At the start of this article, the question of whether DITA could be used for Help was phrased as:

"Can DITA be used to create fully-functional (expanding text links, popups, multimedia, tables, etc), professional-looking (using CSS), context-sensitive Help with a table of contents, index and full-text search in a tri-pane display?"

As it stands, DITA cannot match the feature-set of traditional Help Authoring Tools, particularly those involving DHTML. A DITA-based authoring tool won't provide a means for including DHTML effects, including popups and expansion links). However, DITA can nonetheless be used to create professional-looking Help files with the core functionality of Help files: tables of contents, indexes, links, graphics, and multimedia. With a little bit of post-processing, context-sensitive Help from DITA source is also possible.

With some minor changes to the DITA standard (and to the DITA Open Toolkit), context-hooks could be stored within the DITA files, and window definitions and secondary window link functionality could be provided. This would strengthen DITA's position as a viable Help authoring environment.

---

Links

• http://www.hatmatrix.com/ (http://www.hatmatrix.com/)
• Sample External Link to External Web Site (http://www.structuredauthoring.info/)
• Sample Local Link to External Web Site (http://www.structuredauthoring.info)
• workarounds (#concept_52CCE2C94B314B6C90616C29D359DD6F/section_CE7961C0F34040B8896DA44C33A4D0B8)
• workaround (#concept_52CCE2C94B314B6C90616C29D359DD6F/section_CE7961C0F34040B8896DA44C33A4D0B8)
• Project File (#concept_52CCE2C94B314B6C90616C29D359DD6F/section_2CE19EF5C31E40AFB548632BC2B86BBD)
• workaround (#concept_52CCE2C94B314B6C90616C29D359DD6F/section_CE7961C0F34040B8896DA44C33A4D0B8)
• Project File (#concept_52CCE2C94B314B6C90616C29D359DD6F/section_2CE19EF5C31E40AFB548632BC2B86BBD)

---