Using the IDL Assistant Help System

IDL versions 6.2 through 6.4 used a cross-platform help viewer — IDL Assistant — based on the help viewer used by the Qt development toolkit from Trolltech. Although the IDL Assistant help viewer has been replaced as IDL's default help viewer in version 7.0, it is still included in IDL distributions as an option for user-created help systems.

This section discusses the following topics relating to creating help systems for the IDL Assistant help viewer:

Using the IDL Assistant Help Viewer

This section describes how to use the IDL Assistant application. For information on creating help content that uses the IDL Assistant for your own IDL applications, see the sections that follow.

The Main Window

The IDL Assistant main window contains the text of the current topic. Within the main window you can:

The Sidebar

The IDL Assistant sidebar provides four tabs that allow you to navigate through the specified documentation set. All of the tabs provide a context menu that allows you to open the selected topic the current tab, a new tab, or a new window.

The Contents Tab

The Contents tab displays a hierarchical listing of the contents of the various books in the specified documentation set.

The Index Tab

The Index tab provides a keyword index of the contents of the specified documentation set. Enter a text string in the Look For: field to see keywords that match the string.

The Search Tab

The Search tab allows you to search the text of the specified documentation set for words or phrases. Text matching your search string is highlighted when a topic is displayed in the main window.

Tip
Words or phrases entered in the Search tab are not case sensitive.

To search for words, enter one or more strings in the Searching for: field, separated by spaces and click Search. IDL Assistant displays a list of topics that contain all of the words you entered.

To search for a phrase, enclose the phrase in single or double quote marks.

The list of topics containing the search words or phrase is displayed as a list ranked roughly according to the number of occurrences of the words or phrases, with the topics containing the largest number of occurrences listed given higher rankings.

Allowed Characters

The following characters are allowed in the Search tab:

All other characters are disallowed; you cannot enter them in the Searching for: field.

Warning
Searches that contain single-character strings (such as "a" or "8") are not allowed and will return no results. This is true even when the single character is combined with a punctuation character such as a hyphen. For example, searching for the string "8-bit" will return no results.

Examples 

The Bookmarks Tab

The Bookmarks tab allows you to save links to specific topics in the IDL documentation set for easy reference.

The Menu Bar

The IDL Assistant menu bar runs across the top of the IDL Assistant window, and provides access to the features listed below. Keyboard shortcuts to invoke various menu items are listed in the menus themselves.

The Tool Bar

The IDL Assistant tool bar provides quick access to a subset of the features available via the menubar.

Text Zoom

Select Zoom in or Zoom out from the View menu to change the size of the text in the IDL Assistant main window.

The smoothness of the text zoom operation depends on the ability of the operating system to provide fonts of the appropriate size for the zoomed text. On platforms that provide robust font-management mechanisms, the Zoom operations will work smoothly. On platforms that provide more limited font support, a single Zoom operation may, depending on the current text size and font support, change the text size for only some text elements in the main window, or none at all. In these cases, repeated applications of the Zoom operations may change the text size.

If you find that the text zooming feature does not work adequately with the default fonts, try changing the fonts used by IDL Assistant (see Settings for details.) On platforms that use a set of fixed-size fonts, choosing a font with a larger number of available sizes will allow smoother text zooming.

Printing

Select Print from the File menu or toolbar to display a platform-native Print dialog that allows you to select a printer on which to print.

Note
Currently, the only text range option available is All. Printing all will print the entire contents of the topic currently displayed in the main window.

Tip
The quality of the printed output from IDL Assistant depends on the platform and printer in use. For high-quality printed output, consider printing from the PDF version of the document you are viewing.

Settings

Select Settings from the Edit menu to display a tabbed dialog that allows you to control several IDL Assistant settings.

General Tab

The General tab allows you to select fonts for text display in the main window. By default, the Font is set to Helvetica, and the Fixed Font is set to Courier.

Tip
Depending on the configuration of your system, you may be able to select alternate fonts that provide better appearance or smoother zooming behavior than the defaults. This is especially true on UNIX systems that have a limited set of fonts available. Trying different font settings may improve both the legibility of the text and the ability to zoom in the IDL Assistant viewer.

The General tab also allows you to select a color for hyperlinks and specify whether the links should be underlined. Depending on your platform, changing these values may not produce the effect you expect.

Web Tab

The Web tab allows you to define the web browser that should be invoked when you click on a hyperlink that refers to a web site rather than to a file in the IDL documentation set.

The Web tab also allows you to specify an HTML file that should be displayed when you select Home from the Go menu or click the Home toolbar icon.

PDF Tab

The PDF tab allows you to define a Portable Document Format (Adobe Acrobat) file browser that should be invoked when you click on a hyperlink that refers to a PDF file.

Note
If you choose to define your PDF file browser as Adobe Acrobat, you must use version 7 or later.

Format of an IDL Assistant Help System

The IDL Assistant help viewer displays basic HTML-format files that use a subset of the tags defined by the HTML 3.2 specification. The help viewer does not handle Cascading Style Sheets, Javascript, or frames. Basic HTML tables are supported, but some table features defined in HTML 3.2 — notably the <CAPTION> tag and explicit control of table column widths — are not supported.

An IDL Assistant help system consists of:

Creating Help Content

You can create HTML-format help content using any text editor or HTML authoring tool. Make sure that HTML files you intend to display in the IDL Assistant help viewer do not incorporate Javascript, JScript, ActiveX elements, or frames.

HTML Formatting

You can use most of the text formatting tags supported by the HTML 3.2 format in files intended for display in the IDL Assistant help viewer. If you include Cascading Style Sheet information, it will be quietly ignored by the help viewer.

Directory Structure and File Naming

Place all of the HTML content files for your help system in the same directory that contains your .adp file. You are free to choose any file naming convention you prefer for your help system's HTML files. Note, however, that IDL will interpret the Value argument to the ONLINE_HELP procedure as the name of an HTML file in the same directory as your .adp file. See "ONLINE_HELP" (IDL Reference Guide) for additional details related to how IDL interprets the Value argument.

Image Files

Image files referenced by your help system's HTML files can be in PNG, GIF, or JPEG format. Image files do not need to be in the same directory as the HTML content files for your help system; by convention, image files are stored in a subdirectory of the content directory.

Creating an Assistant Document Profile

The .adp file is an XML-format file that defines properties of your help system, constructs a hierarchical table of contents, and provides keyword index terms for your help topics.

You must ensure that your help system's .adp file is a valid XML file. This means that each element must contain values for all required attributes and must be properly closed. If the structure of the .adp file is not valid, IDL Assistant will fail to load the information in the .adp file, and no table of contents or index will be available for your help system.

The following is a very simple example of an .adp file that defines the help system properties and a single help topic with two keyword index terms:

<!DOCTYPE DCF> 
<assistantconfig version="3.3.0"> 
   <profile> 
      <property name="name">MyApp Version 1.2</property> 
      <property name="title">My Help System</property> 
      <property name="startpage">home.html</property> 
      <property name="aboutmenutext">About My App</property> 
      <property name="abouturl">about_my_app.txt</property> 
      <property name="assistantdocs">.</property> 
   </profile> 
   <DCF ref="my_home.html" title="My Help"> 
      <section ref="Topic1.html" title="Topic1"> 
         <keyword ref="Topic1.html">Index one</keyword> 
         <keyword ref="Topic1.html#anchor">Index two</keyword> 
      </section> 
   </DCF> 
</assistantconfig> 

The individual XML elements that make up an .adp file are described below.

<!DOCTYPE> Element

The .adp file must begin with an XML <!DOCTYPE> element that defines the file as being of type "DCF." The first line of an .adp file must always be:

<!DOCTYPE DCF> 

Element Value

Elements of this type do not contain an element value, and do not need to be closed.

<assistantconfig> Element

All of the content of the .adp file is enclosed in an <assistantconfig> element.

Element Value

Elements of this type contain <profile> and <DCF> elements.

version Attribute

When creating content for the IDL Assistant help viewer, set the version attribute to the value "3.3.0":

<assistantconfig version="3.3.0"> 

<profile> Element

The <profile> element contains a set of <property> elements that define values used by the entire help system. The allowed attribute values are described in the <property> Element section, below.

Element Value

Elements of this type contain <property> elements.

<property> Element

Each <property> element defines a value used to configure the help viewer application.

Element Value

The element value is a text string. Each element must include a name attribute with one of the attribute values listed below.

name

The value of a <property> element with the name attribute set equal to "name" is the identifier for the help system. IDL Assistant will use this value when creating index, full-text search, and bookmark filenames for your help system. For example, the following <property> element defines the name of the help system as "MyApp Version 1.2":

<property name="name">MyApp Version 1.2</property> 

title

The value of a <property> element with the name attribute set equal to "title" is string displayed in the title bar of the IDL Assistant help viewer application window. For example, the following <property> element defines the title as "My Help System":

<property name="title">My Help System</property> 

startpage

The value of a <property> element with the name attribute set equal to "startpage" is a URL (relative to the .adp file) to the HTML file that will be displayed when a user clicks the IDL Assistant Home button or selects Home from the Go menu. For example, the following <property> element defines the start page as "home.html":

<property name="startpage">home.html</property> 


Note

When the ONLINE_HELP procedure opens a help system, if no HTML file is specified for display via the Value argument, the help viewer will attempt to open a file named home.html in the same directory as the .adp file. As a result, in most cases the value of the <property> element with the name attribute set equal to "startpage" should be home.html.

aboutmenutext

The value of a <property> element with the name attribute set equal to "aboutmenutext" defines a string that will be included as a menu item in the IDL Assistant Help menu. Selecting the menu item displays the contents of the file defined by a <property> element with the name attribute set equal to "abouturl" in a modal dialog. For example, the following <property> element defines the Help menu item string as "About My App":

<property name="aboutmenutext">About My App</property> 

This element is optional. If no <property> element with the name attribute set equal to "aboutmenutext" exists, the menu item is not displayed in the IDL Assistant Help menu.

abouturl

The value of a <property> element with the name attribute set equal to "abouturl" is a URL (relative to the .adp file) to a text or HTML file that will be displayed in a modal dialog when the user selects the menu item defined by a <property> element with the name attribute set equal to "aboutmenutext". For example, the following <property> element defines the "About My App" menu item URL as "about_my_app.txt":

<property name="abouturl">about_my_app.txt</property> 

This element is optional. If no <property> element with the name attribute set equal to "aboutmenutext" exists, there is no need to define this element.

Warning
The "about" dialog is intended to display a small block of text. Some basic HTML text formatting is allowed, including font face, style, and point size. There is no explicit control over the size or configuration of the dialog.

assistantdocs

The value of a <property> element with the name attribute set equal to "assistantdocs" is the path to the directory that contains the file assistant.html, which contains information on the use of the IDL Assistant help viewer. The path can be either absolute or relative to the directory that contains the .adp file. This file is displayed when the user selects IDL Assistant Manual from the Help menu.

The assistant.html file used by IDL Assistant itself is located in the help/online_help subdirectory of the IDL distribution. If you know the relative path from your .adp file to this location, you can include it in the <property> element and users of your help system will be able to display the "help on help" content from the IDL online help system. If you do not know the relative path (perhaps because you do not know where users of your application will install it), you may wish to create your own assistant.html file containing "help on help" information.

Note
The file must be named assistant.html. The <property> element contains only the path to the directory that contains this file.

For example, suppose you know that your application (along with its help system) will only be installed on UNIX systems that have IDL installed in the default location (/usr/local/itt). You could set the value of the <property> element as follows to allow your users to view the "help on help" topic from the IDL online help system:

<property name="assistantdocs"> 
   /usr/local/itt/idl/help/online_help 
</property> 

Similarly, if you choose to create your own assistant.html file and place it alongside your other help system content, you could set the value of the <property> element as follows:

<property name="assistantdocs">.</property> 

<DCF> Element

A <DCF> element represents a single "book" in the help system, and encloses all of the <section> elements that make up the book. In the IDL Assistant help viewer, a <DCF> element is represented by a collapsible book icon in the Contents tab. Clicking on the book icon displays the topic associated with the <DCF> element in the main help window and either displays or collapses the hierarchy contained within the element in the Contents tab.

Element Value

Elements of this type contain <section> elements.

ref Attribute

The ref attribute of a <DCF> element specifies the path to the HTML file that will be displayed in the main window when the user clicks on the book icon in the Contents tab.

The path to the HTML file should be relative to the .adp file. You can optionally include an HTML anchor tag after the file name.

title Attribute

The title attribute of a <DCF> element specifies the text that will be displayed next to the book icon for the element in the Contents tab.

For example, the following <DCF> element specifies that the book icon for the enclosed group of topics will be titled "What's New" and will display the file whatsnew.html positioned to the HTML anchor tag anchor1:

<DCF ref="./whatsnew.html#anchor1" title="What's New"> 

<section> Element

A <section> element represents a single topic in the help system. Topic titles are displayed in the table of contents. <section> elements can be nested; the hierarchy defined by the nested section elements is reflected in the Table of Contents display.

Clicking on the section title displays the topic associated with the <section> element in the main help window and either displays or collapses the hierarchy contained within the element in the Contents tab.

Element Value

Elements of this type contain <section> and <keyword> elements.

ref Attribute

The ref attribute of a <section> element specifies the path to the HTML file that will be displayed in the main window when the user clicks on the topic title in the Contents tab.

The path to the HTML file should be relative to the .adp file. You can optionally include an HTML anchor tag after the file name.

title Attribute

The title attribute of a <section> element specifies the text that will be displayed as the section title in the Contents tab.

For example, the following nested <section> elements define three topics "contained" by the topic titled "Chapter 1":

<section ref="chap1.html" title="Chapter 1"> 
   <section ref="chap1a.html#anchor1" title="Subhead 1"></section> 
   <section ref="chap1b.html#anchor1" title="Subhead 2"></section> 
   <section ref="chap1b.html#anchor2" title="Subhead 3"></section> 
</section> 

<keyword> Element

A <keyword> element defines an entry in the help system's keyword index. Keyword index entries are displayed in the Index tab.

Element Value

The element value is a text string that contains the keyword index entry text.

The keyword index may be hierarchical. If a <keyword> element's value string includes the colon character, the text will be treated as a multi-level index entry. Thus, the value

top level entry:subentry1 

would be displayed in the Index tab as

top level entry 
   subentry1 

When the <keyword> element values are displayed in the Index tab, they are alphabetized by level. All of the top-level entries are alphabetized, and each top-level entry's subentries are then alphabetized.

ref Attribute

The ref attribute of a <keyword> element specifies the path to the HTML file that will be displayed in the main window when the user clicks on the entry in the Index tab.

The path to the HTML file should be relative to the .adp file. You can optionally include an HTML anchor tag after the file name.

For example, the following <keyword> element defines an index entry with the title "Thingamajig" that corresponds to the HTML anchor thingamajig in the HTML file myroutines1.html:

<keyword ref="myroutines1.html#thingamajig">Thingamajig</keyword> 

Optional Help System Files

The files described in this section are not required for your help system to function, but may be useful.

About file

The "about" file is displayed when the user chooses the "about" entry from the IDL Assistant Help menu, if it exists. If you choose to create this file, it can be either a text file or an HTML file containing basic HTML tags. See "aboutmenutext" and "abouturl" under <property> Element for details.

TopicNotFound.html

The TopicNotFound.html file is displayed when the Value argument to the ONLINE_HELP procedure is supplied, but the specified file is not found. See Displaying Help Topics below for additional information.

Displaying Help Topics

To display a topic within your help system, use the ONLINE_HELP procedure, specifying name of your .adp file as the value of the BOOK keyword. For example, if your .adp file is named myapp.adp, and you have placed the help system in a directory that is included in IDL's help path, you would use the following ONLINE_HELP command:

ONLINE_HELP, BOOK="myapp.adp" 

See Paths for Help Files for more on setting IDL's help path. Alternatively, if you know the full path to the .adp file, you could use an ONLINE_HELP command like the following:

ONLINE_HELP, BOOK="/usr/local/myapp/help/myapp.adp", /FULL_PATH 

In most cases, it is more appropriate to set IDL's help path to include your help system when your application runs, as described in Adding a Directory to the Help Path at Runtime.

To display a specific topic from your help system, include the Value argument to the ONLINE_HELP procedure:

ONLINE_HELP, "InterestingTopic", BOOK="myapp.adp" 

When IDL executes this command, it will do the following things:

Paths for Help Files

You can specify the search path for help files via the !HELP_PATH system variable. Placing your help files in a directory included in the help path means that you do not need to include the full path in your call to the ONLINE_HELP procedure; supplying the name of the help file is enough.

Note
IDL searches the directories specified by !HELP_PATH and chooses the first instance of a file that matches the name you specify via the BOOK keyword to ONLINE_HELP. If no file extension is included in the value of the BOOK keyword, IDL will search each directory in !HELP_PATH until it finds a matching file with one of the following file extensions, in this order: .adp, .chm (Windows only), .hlp (Windows only), .pdf, .html, .htm. You can override this behavior by explicitly specifying the desired file extension.

By default, !HELP_PATH contains the help subdirectory of the main IDL directory. To change the default value of !HELP_PATH, change the value of the IDL_HELP_PATH preference.

To change the value of !HELP_PATH during a single IDL session, simply assign a new value to the system variable. For example, to add a directory of your choice to the end of the default help path, you could use the following command:

!HELP_PATH=!HELP_PATH+'mypath' 

where mypath is a valid path string, including the appropriate path element separator character for your platform.

Adding a Directory to the Help Path at Runtime

If you distribute your application to users who install it on their own systems, you have no way of knowing in advance how to set the value of !HELP_PATH.

Suppose you have an application named myapp, installed in an unknown location your end-user's computer. The help system for myapp is located in a subdirectory of your application's directory named help. Including the following block of code in myapp.pro would be one way to determine the location of your help system at runtime, and set the !HELP_PATH system variable accordingly.

myapp_info = ROUTINE_INFO('myapp', /SOURCE) 
myapp_path = FILE_DIRNAME(myapp_info.path) 
myapp_help_path = myapp_path + PATH_SEP() + 'help' 
!HELP_PATH = !HELP_PATH + PATH_SEP(/SEARCH_PATH) + myapp_help_path 

Once the help path is set in this manner, you can simply provide the name of the .adp file for your help system as the value of the BOOK keyword to the ONLINE_HELP procedure.