IDL Reference Guide: Procedures and Functions

ONLINE_HELP

The ONLINE_HELP procedure invokes IDL's online help system. If called with no arguments, it starts the help viewer with the default IDL help file displayed.

IDL's online help system uses a cross-platform help viewer — IDL Assistant — based on the help viewer used by the Qt development toolkit from Trolltech. For information on using the help viewer, see Getting Help with IDL.

The IDL online help system comprises a set of HTML and image files governed by a special index (*.adp) file. For information on creating a help system that can be displayed in IDL's help viewer, see Providing Online Help For Your Application.

In addition to online help systems created for the IDL help viewer, the ONLINE_HELP procedure can display files in the following formats:

Syntax

ONLINE_HELP [, Value] [, BOOK=`filename'] [, /FULL_PATH] [, /QUIT]

Windows-Only Keywords: [, /CONTEXT]

Arguments

Value

An optional string that specifies the topic or sub-topic to be displayed, depending on the type of help file in use. Value is interpreted differently depending on the value of the BOOK keyword:

Keywords

BOOK

Set this keyword to a string containing the name of the help file to be displayed. If BOOK is not specified, IDL will search the directories in !HELP_PATH for a file whose base name matches Value. If neither the BOOK keyword or the Value argument is specified, IDL will open the default IDL will display the IDL online help system's home page.

If BOOK is specified, the way it is interpreted depends on the type of file specified, as determined by the file's extension:

If no file matching the specification is found, an error message is displayed in the IDL help viewer.

CONTEXT

This keyword is only available on Windows platforms.

Set this keyword to indicate that the Value argument is an integer value that represents the context number of a help topic to be displayed in the Microsoft Windows HTMLHelp viewer or the older Windows Help viewer. This keyword is intended for use with user-compiled Windows help files (*.chm or *.hlp) that contain topics that have been mapped to specific context numbers when they were compiled using the [MAP] section of the help project file. Specifying a non-existent context number causes an error dialog to be displayed. For more information on how to create help files with context numbers, see the documentation for the help system compiler that you are using.

FULL_PATH

Set this keyword to indicate that the value of the BOOK keyword is a full and complete path to the help file, including any necessary directory information, and a file extension. If FULL_PATH is not specified, ONLINE_HELP searches the directories referred to by the !HELP_PATH system variable to locate the file, and the file extension is optional.

QUIT

Set this keyword to close the Help viewer.

Displaying HTML and PDF Files under UNIX

To display an HTML or PDF file on a Windows system, IDL simply instructs Windows to open the specified file and leaves it to the operating system to choose the correct application based on the file type. UNIX systems have no cross-platform standard facility for associating different types of files with specific applications, so the situation is slightly more complicated.

HTML Files

When the BOOK keyword specifies an HTML file (that is, when the file name ends with any of .html, .HTML, .htm, or .HTM), IDL calls a shell script located in the IDL distribution. The shell script then launches a web browser with the specified file as its argument. On Macintosh systems, IDL's default is to call the Open command along with the filename, allowing the operating system to choose the correct application to open the file. On other UNIX systems, IDL assumes that it should launch the Netscape web browser, and that the netscape command is located in one of the directories specified by the PATH environment variable. Individual users can override the default behavior by setting environment variables to specify either a different browser or an entirely different shell script.

See the comments in the online_help_html script located in the bin subdirectory of the IDL distribution for details on setting the relevant environment variables.

PDF Files

When the BOOK keyword specifies a PDF file (that is, when the file name ends with either .pdf or .PDF), IDL calls a shell script located in the IDL distribution. The shell script then launches a PDF file viewer application with the specified file as its argument. On Macintosh systems, IDL's default is to call the Open command along with the filename, allowing the operating system to choose the correct application to open the file. On other UNIX systems, IDL assumes that it should launch the Acrobat Reader application, and that the acroread command is located in one of the directories specified by the PATH environment variable. Individual users can override the default behavior by setting environment variables to specify either a different viewer or an entirely different shell script.

See the comments in the online_help_pdf script located in the bin subdirectory of the IDL distribution for details on setting the relevant environment variables.

Examples

The following example uses the ONLINE_HELP procedure to launch the help viewer to display information on the FFT function:

ONLINE_HELP, 'fft'  

This Windows-only example displays the topic corresponding to context number 100 in a traditional Windows help file.

ONLINE_HELP, 100, /CONTEXT, /FULL_PATH, $  
   BOOK='C:\keith\myfile.hlp'  

This cross-platform example displays an HTML file in the system's default web browser.

ONLINE_HELP, BOOK='myfile.html'