Leximation AIR Help Plug-in

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

The Leximation AIR Help DITA-OT plug-in is not yet publicly available; to request a Beta version of this plug-in, please visit www.leximation.com/airhelp.

Overview

“AIR Help” is a term that refers to any user assistance application that has been developed using Adobe’s AIR (Adobe Integrated Runtime) technology and does not specifically define appearance or functionality. 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 8” and MadCap Software’s “Flare 4.” Adobe also offers a utility called “RoboHelp Packager for AIR” which allows you to generate an AIR Help file from a RoboHelp WebHelp project (for use with older versions of RoboHelp). RoboHelp 8 allows you to import DITA files which can then be exported to an AIR Help package.

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:

Tabbed navigation panels for Contents, Index, and Search
Full text search that allows for both local and remote search indexes
Forward, Back, Home buttons as well as Next/Previous Browse buttons that follow the structure of topics in the Contents tab
The ability to make context sensitive calls from an external application
Position and size of window is preserved between sessions
Sync with TOC functionality

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

Setup and configuration

A new feature in the DITA-OT 1.5 allows for external hooks into the indexing pipeline making it possible to generate the alternate format index required by this plug-in (in earlier versions a recompile of dost.jar was required).

In order to compile and package up an AIR file, you must have the Flex and AIR SDKs installed (both are freely available from Adobe). If you have Flex Builder 3 installed, both of these SDKs are included in the installation.

To install this plug-in:

Extract the ZIP archive into the DITA-OT/demo directory to create an lmi-airhelp directory which contains all of the necessary files.
If you have Flex Builder 3 installed, continue to the next step, otherwise download and install the following:
- Adobe Flex 3 SDK (http://www.adobe.com/products/flex/flexdownloads/)
- Adobe AIR 1.5 SDK (http://www.adobe.com/products/air/tools/sdk/)
Locate the lmi-airhelp/integrator.xml file. Modify the property values so they are correct for your system. In particular, the FLEX.SDK_HOME and AIR.SDK_HOME properties, but possibly others. Search for “AIRHELP PROPERTIES.”
Add the lmi-airhelp.jar file to the CLASSPATH. If you're using the startcmd.bat file to set up the environment, add %DITA_DIR%demo\lmi-airhelp\lmi-airhelp.jar; to the CLASSPATH declaration:
```
set CLASSPATH=%DITA_DIR%demo\lmi-airhelp\lmi-airhelp.jar; ...
```
Integrate the plugin with the OT. Run the integration command:
```
ant -f integrator.xml
```

After installation, you can test the install by copying the sample_airhelp.xml file into the DITA-OT/ant/ directory. Run the startcmd.bat file and enter the following:

ant -f ant/sample_airhelp.xml

Assuming the build is successful, you should end up with a DITA-OT/ant/out/airhelp/ directory. In that directory you'll see an airhelp-test.bat file. Run the batch file to launch the new AIR Help file. Test the index and search to make sure that all’s well.

In order to build an AIR file that can be sent to others, run the airhelp-packager.bat file. The packager batch file assumes that you have set up the digital certificate information properly in the integrator.xml file. For information on creating a self-signed certificate, see http://help.adobe.com/en_US/AIR/1.5/devappshtml/WS5b3ccc516d4fbf351e63e3d118666ade46-7f74.html

The plug-in creates the following files:

TOC file (<mapname>.ahtoc)
Keyword index file (<mapname>.ahix). Displays on the Index tab and is built from available indexterm elements.
“Local” full text search index (_searchIndex.xml). Displays on the Search tab and is created by parsing the generated HTML files.
The AIR Help project file (airhelp.ahp)
The AIR application file (airhelp-app.xml)
Compiled SWF (airhelp.swf)
Batch files for testing and packaging of the AIR file (airhelp-test.bat and airhelp-packager.bat)

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

/map/topicmeta/copyright or /bookmap/bookmeta/bookrights
/map/topicmeta/prodinfo/prodname
/map/topicmeta/prodinfo/vrmlist/vrm (the last one)
/map/topicmeta/prodinfo/prognum
/map/topicmeta/othermeta/@name=’remote-search-index-url’ (@content specifies the location for the remote search index which is loaded on startup)

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