Leximation AIR™ Help Plug-in

This topic introduces AIR Help and provides information about generating AIR Help from DITA.

The Leximation AIR Help DITA-OT plug-in is not yet publicly available; information about the availability of this plug-in will be posted to www.leximation.com/airhelp.

Overview

AIR Help is an evolving new option for delivering online user assistance. This Help delivery format does not specifically define appearance or functionality, but refers to any user assistance application that was developed with Adobe’s AIR (Adobe Integrated Runtime) technology. Applications developed using AIR can be installed on the Mac, Windows, and Linux operating systems, and are highly customizable, making it an ideal technology from which to develop an online Help deliverable.

Currently there are two commercially available products for generating AIR Help, Adobe’s “RoboHelp® Packager for AIR” and MadCap Software®’s “Flare.” RoboHelp Packager for AIR (beta) allows you to export an AIR Help file from a RoboHelp WebHelp project. At this time, there is no connection between RoboHelp and DITA other than the option of authoring DITA files in FrameMaker and importing the FrameMaker files into RoboHelp. Flare offers AIR Help as one of the standard output formats from their latest version.

The other option for creating AIR Help is custom development. You can take any browser-based set of HTML files and “wrap” them up in an AIR application. The most basic AIR application is one that contains an embedded web browser (based on WebKit) which essentially lets you present your HTML-based Help in your custom browser.

The Leximation AIR Help DITA-OT plug-in provides a direct path from DITA to AIR Help. This implementation of AIR Help provides the following features:


Additionally, you may customize the AIR Help interface to add features or to modify the appearance as needed.

Setup and configuration

Currently, in order to install and use this plug-in you must recompile the dost.jar file. For this reason, the plug-in is not publicly available. Updates are being made to the DITA-OT 1.5 that will support the modifications to the indexing pipeline required by this plug-in. Setup and configuration information will be made available once the OT has been updated.

Assuming the plug-in has been installed, the following information will apply.

For the most basic output, no extra effort is needed. Run your DITA map through the plug-in, and it will:


The following data is used from the map file when building the AIR file:


The Index is built from available indexterm elements.

After a successful build, just run the airhelp-test.bat batch file to view and test the new AIR Help file. When you’re ready to build the final AIR file, just run the airhelp-packager.bat batch file.

Authoring

No specific authoring requirements are needed.

Integration

Because an AIR Help file is actually a desktop application, you launch the Help system by making a system call to run the executable. If no command-line parameters are provided, the AIR Help file will open with the default topic displayed.

In order to launch the Help system on a specific topic, use the following command-line syntax:

<path/app_executable> <target_topic>

For example, the following call will display the “Image” topic in the DITA Reference AIR Help file:

"c:\program files\ditaref\ditaref.exe" image.html

To launch the Help system with the search panel selected and pre-populated with a query, use the following syntax:

<path/app_executable> "search:using conrefs"

To launch the Help system with an external URL (website) displayed, use the following syntax:

<path/app_executable> http://google.com

Additional command-line parameters can be added as needed.

Because only one instance of each AIR Help application can exist at one time, if you make a system call to the application when one is already running, the result of the new call replaces the running instance.

Output

This plug-in uses the HTML generated by the dita2html target, and only controls the interface features of the “container” application.

Figure 1. Example AIR Help application window

Summary

Because AIR Help is very new and still under development, it may be best for some to wait for further development to be completed. However, because of its cross-platform support and reduced testing effort, you may find that it is worth closer investigation as a potential Help delivery format.

Scott Prentice

Individual

OASIS DITA Help Subcommittee