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 HAT.

Figure 1. 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.

Diagram showing relationships between context strings, context numbers, and 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.

Partial screen capture showing links generated by relationships defined in the relationship table

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

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.

  • HTML Help API
    This article describes how to use the HTML Help API to call Help within Windows 98 and above.
  • Context Sensitive Help Files with HTML Help ver 1.0
    This article describes what's involved in using HTML Help ver 1.0 for context-sensitive Help in Windows 95 or 98.
  • Modifying DITA OT Build Files for CSH
    This topic describes how to modify the DITA OT Tookit files to allow context-sensitive Help map file and alias strings to be added to the Microsoft HTML Help output.
Footer for DITA Output - HyperWrite

Copyright © 1999 HyperWrite Pty Ltd
All rights reserved.


HTML Help API

This article describes how to use the HTML Help API to call Help within Windows 98 and above.

Calling Help From Visual Basic 5.0

Calls from Visual Basic 5 to the HTML Help API are similar to those to the WinHelp API, although different constants are used, and the different functionality of the two Help systems obviates some differences.

There are two ways to declare the HTML Help function:

[Declarations]Declare Function HtmlHelp Lib 'hhctrl.ocx' Alias 'HtmlHelpA' (ByVal hwnd As Long, ByVal LPCSTR As String, ByVal UINT As Long, dwData As Any) As Long

or

[Declarations]

Declare Function HtmlHelpA Lib 'hhctrl.ocx' (ByVal hwnd As Long, ByVal LPCSTR As String, ByVal UINT As Long, dwData As Any) As Long

If you use the second declaration, you will have to use HtmlHelpA in your calls rather than HtmlHelp as in the examples that follow.

The following shows the correct syntax in Visual Basic 5.0 for declaring HTML Help constants.

[Declarations]Public Const HH_DISPLAY_TOPIC = &H0Public Const HH_DISPLAY_TOC = &H1Public Const HH_DISPLAY_INDEX = &H2Public Const HH_KEYWORD_LOOKUP = &HDPublic Const HH_HELP_CONTEXT = &HF

The HH_DISPLAY_TOPIC call is used to open the CHM file, and display a nominated HTML page within the compiled CHM file. For example, if we wanted to start fofp.chm and display the topic 5a58384.htm, the correct Event syntax would be:

[Event]result& = HtmlHelp(hwnd, ByVal 'fofp.chm', HH_DISPLAY_TOPIC, ByVal '5a5868a.htm')

An alternative method of achieving the same result would be:

[Event]result& = HtmlHelp(hwnd, ByVal 'fofp.chm::/5a5868a.htm', HH_DISPLAY_TOPIC, ByVal 0)

By passing a '0' instead of a file name when using the HH_DISPLAY_TOPIC call, you can display the Contents page (or if not defined, the first of the compiled pages) of the nominated CHM file. For example, if we wanted to start fofp.chm and display the contents topic, the correct Event syntax would be:

[Event]result& = HtmlHelp(hwnd, ByVal 'fofp.chm', HH_DISPLAY_TOPIC, ByVal 0)

This call only controls the HTML page in the right window, and does not change the current tab settings.

A call can be passed from the application to direct the Help engine to select the Table of Contents tab in the left pane. For example, let's say the Index tab is currently selected. The following call will leave the right pane displaying the current page (if the nominated CHM file is already displayed), but drive the left pane to show the Table of Contents tab.

[Event]Call HtmlHelp(hwnd, ByVal 'fofp.chm', HH_DISPLAY_TOC, ByVal 0)

In the same way that the Table of Contents tab can be displayed from code, so too can the Index tab be displayed. The following call will leave the right pane displaying the current page (if the nominated CHM file is already displayed), but drive the left pane to show the Index tab.

[Event]Call HtmlHelp(hwnd, ByVal 'fofp.chm', HH_DISPLAY_INDEX, ByVal 0)

HTML Help permits different window attributes to be defined. These window attributes affect the size of the window, button configuration, border width, etc. A specific window can be specified when using any of the HTML Help calls above. The window name is nominated by simply adding a greater than sign (>) and the window name immediately after the CHM file name in the call. For example:

[Event]Call HtmlHelp(hwnd, ByVal 'fofp.chm>small', HH_DISPLAY_INDEX, ByVal 0)result& = HtmlHelp(hwnd, ByVal 'fofp.chm>small', HH_DISPLAY_TOPIC, ByVal '5a5384.htm') result& = HtmlHelp(hwnd, ByVal 'fofp.chm>small', HH_HELP_CONTEXT, ByVal IDH_OKButton)

Being a 16-bit only environment, Visual Basic 3.0 programs cannot invoke HTML Help.

However, 32-bit Visual Basic 4.0 applications can.

The syntax for the declaration is slightly different:

[Declarations]Public Declare Function HtmlHelp Lib 'hhctrl.ocx' Alias 'HtmlHelpA' (ByVal hwnd As Long, ByVal LPCSTR As String, ByVal UINT As Integer, DWord As String) As Long or

[Declarations]

Public Declare Function HtmlHelpA Lib 'hhctrl.ocx' (ByVal hwnd As Long, ByVal LPCSTR As String, ByVal UINT As Integer, DWord As String) As Long

The syntax for the HTML Help declaration in PowerBuilder 5 is:

Function int HtmlHelpA(Int hwnd, string lpcstr, int uint, string dword) LIBRARY 'hhctrl.ocx'

Return to Context Sensitive Help with HTML Help

Parent topic: DITA for Help
Footer for DITA Output - HyperWrite

Copyright © 1999 HyperWrite Pty Ltd
All rights reserved.


Context Sensitive Help Files with HTML Help ver 1.0

This article describes what's involved in using HTML Help ver 1.0 for context-sensitive Help in Windows 95 or 98.

Introduction

In the good old days, help systems for Windows applications were developed for WinHelp, Microsoft's 'Help Engine'. WinHelp was tightly integrated into Windows itself. An application calling for Help would pass the request to the Windows Applications Programming Interface (API), which included a set of routines for communicating with WinHelp. This subset of the Windows API was known, logically enough, as the WinHelp API. The calling application would pass parameters to the WinHelp API to specify what help file to open, what mode to open in, what topic to display, and what window to use. The method of identifying topics through 'context strings' and 'context IDs' required programmer and help author to work closely together.

From a user's point of view, the system was beautiful (when implemented correctly). The user simply pressed F1, or an onscreen 'Help' button or menu item, and the help file would instantly open at the correct topic.

Back in the good old days, WinHelp was the dominant hypertext viewer for PC users.

Then came the Internet.

The Internet's World Wide Web is a hypertext publishing platform. It uses Hypertext Markup Language (HTML) as its medium. HTML is similar in functionality to WinHelp, but is technically very different. From a reader's point of view, HTML is inferior in most respects, particularly across a corporate LAN. It is slower, it doesn't support text formatting, its appearance varies from browser to browser, it doesn't support pop-ups or indexes, it can't interact with the operating system, and it can't be used for context-sensitive help. In two areas, however, HTML is superior. It is quicker and more efficient over a telephone connection, and it supports online forms.

The most important difference is that WinHelp is a mature product, whereas HTML is in its infancy.

The forms processing capabilities of HTML open up the opportunity for businesses to dramatically improve efficiency by having once-only entry of data. For example, rather than have an employee fill in a leave application by hand and then have someone else key that data into the payroll system, the employee can complete an online form that automatically updates the payroll system. So HTML can be a documentation and business application, while poor old WinHelp can only ever be a documentation application.

Microsoft has applied itself to the task of addressing the limitations of HTML for use as a context-sensitive help system. The resullt is HTML Help, an ingenius system for creating document content in standard HTML, and then compiling the documents into a help system unit.

Although HTML Help documents can be viewed using standard HTML browsers, the help system functionality is only available when used with the special HTML Help viewer, HH.EXE.

When an application calls help, it needs to nominate the name of the help file, and the context number of the page to display. In Visual Basic, this call looks something like this:

[Declarations Section]Declare Function HtmlHelp Lib 'hhctrl.ocx' Alias 'HtmlHelpA' (ByVal hwnd As Long, ByVal LPCSTR As String, ByVal UINT As Long, dwData As Any) As Long

Public Const HH_HELP_CONTEXT = &HF Public Const IDH_OKButton = 6010

[Event]

result& = HtmlHelp(hwnd, ByVal 'fofp.chm', HH_HELP_CONTEXT, ByVal IDH_OKButton)

Whereas WinHelp's context-sensitivity was made possible through the WinHelp API, HTML Help's context-sensitivity follows the same approach - and is known as the HTML Help API. The API is made up of an ActiveX object called hhctrl.ocx, and an associated htmlhelp.dll Dynamic Link Library.

The event code above would result in the Compiled HTML Help file fofp.chm being opened within HH.EXE, and the topic with a context id of 6010 being displayed.

It is useful to think of the context string (IDH_OKButton in this case) as the human being's reference, and the context number (6010 in this case) being the computer's reference.

See Also: Other Ways of Calling Help

To apply a context string of IDH_OKButton and the context number 6010 (in the example above) to a topic in the CHM file, the help author needs to relate the context string with the topic HTML file name, and then relate the context string to the context number.

Screen capture showing API button in HTML Help Workshop Within the HTML Help Workshop's project tab, there is an HtmlHelp API Information button. This button displays a dialog box that allows you to nominate a header file (containing the context string and context number pairs), and an Alias list (containing the association between the context string and the HTML file name).

Screen capture showing API Window in HTML Help Workshop Adding a header file is simply a matter of browsing for the file from the HtmlHelp API Information dialog box's Map tab, as at right.

A C header file might contain an entry for our example context hooks as follows.

#define IDH_OKButton 6010

The Alias list would include the string-to-filename connection as follows.

Screen capture of Alias dialog box in HTML Help Workshop

This completes the process.

If the user wants to know what the OK button does, he or she presses the [F1] key when the OK button is highlighted. The programmer has added the Event code to the [F1] properties of the OK button object, so the fofp.chm file opens and displays the topic 5157ca1.htm.

As simple as that.

Parent topic: DITA for Help
Footer for DITA Output - HyperWrite

Copyright © 1999 HyperWrite Pty Ltd
All rights reserved.


Modifying DITA OT Build Files for CSH

This topic describes how to modify the DITA OT Tookit files to allow context-sensitive Help map file and alias strings to be added to the Microsoft HTML Help output.

Before starting this procedure, you must have DITA Open Toolkit 1.3 installed locally on your PC.

This procedure is used to modify the DITA Open Toolkit build files to allow an external map file reference and alias strings to be added to the HTML Help Project file before building, as part of the transformation to Microsoft HTML Help (CHM) format.

  1. Open the file build_dita2htmlhelp.xml, from the DITA OT root directory, in a text editor or an XML editor.
  2. Find the <target> node with a name of dita.map.htmlhelp. To the depends attribute, add dita.map.htmlhelp.ali.
  3. Save the file.
  4. Open the file map2hhc.xsl from the DITA OT /xsl directory, in a text editor or an XML editor.
  5. Find the Command line parameters section of the file, and alter the HELPALIAS parameter line so it reads <xsl:param name="HELPALIAS" select="'hw_csh.ali'"</xsl:param> (where hw_csh.ali is the name of the alias file you want to include in the CHM file).
  6. Also in the Command line parameters section, alter the HELPMAP parameter line so it reads <xsl:param name="HELPMAP" select="'hw_map.ali'"</xsl:param> (where hw_csh.h is the name of the alias file you want to include in the CHM file).

The main control build file for HTML Help transformations now knows to process a target of dita. map.htmlhelp.ali, contained in an external resource file named dita_hw_csh.xml. This file is included in the build within the WinAnt build file. The transformation files now include the necessary information to add an include line in the [ALIAS] and [MAP] sections of the HHP file.

Parent topic: DITA for Help
Footer for DITA Output - HyperWrite

Copyright © 1999 HyperWrite Pty Ltd
All rights reserved.