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.
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
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.
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.
- Secondary window links
- Rich text popups
- Breadcrumbs, browse sequences and related topic links
- Next/Previous links
- Table of Contents
- Glossary of Terms
- 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)
- 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.
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.
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:
- copyright information
- product information
- 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.
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.
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.
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 DITA, the <xref>
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.
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.)
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.
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.
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 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.
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.
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
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.)
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.
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.
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.
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.
DITA markup includes solid provision for accessibility, such as alternative text attributes, throughout its elements.
The standard DITA Open Toolkit transformation to HTML and HTML Help can generate standards-compliant XHTML output without fuss.
|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.
|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.
|Master page||None. Difference in philosophy.|
|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.|
|Modular Help||Limited.||DITA OT improvements would add opportunities.|
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.