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.
| Note |
? command, which is a shorthand for the ONLINE_HELP procedure, is intended for use at the IDL command line.
The online help viewer used by ONLINE_HELP depends on the operating system in use and the type of help document specified:
UNIX: IDL online help documents are provided in Adobe Acrobat PDF format. To use ONLINE_HELP (or the ? command), you must have version 4.0.5 or later of either the Acrobat Reader or the full Acrobat application installed on your system, and the corresponding acroread command must be available in a directory included in your UNIX PATH environment variable. See the Installing and Licensing IDL manual for details.
| Note |
http://www.adobe.com. In addition, the most current version of Acrobat Reader available for each platform supported by IDL at the time of IDL's release is included on the IDL CD-ROM.
In addition, if a web browser is installed on the system and available for use by IDL, HTML files can be displayed. See Displaying HTML Files under UNIX for details.
Windows: IDL online help is built around the standard Windows help facilities. Windows HTML Help files (.chm) as well as traditional Windows help files (.hlp) can be displayed. In addition, if Adobe Acrobat is available on the system, PDF files can be displayed. If a web browser is available on the system, HTML files can be displayed. ONLINE_HELP will automatically determine which help format to use based on the file name.
For a more complete description of the Unix and Windows help systems, see Providing Online Help For Your Application.
ONLINE_HELP [, Value] [, BOOK=`filename'] [, /FULL_PATH] [, /QUIT]
UNIX-Only Keywords: [, /FOLD_CASE] [, PAGE=pageno] [, /SUPPRESS_PLUGIN_ERRORS]
Windows-Only Keywords: [, /CONTEXT] [, /TOPICS]
An optional string that contains the name of a topic to be displayed.
Under UNIX, Value is the name of a topic to be displayed. If Value is omitted, if the specified topic does not exist in the specified or default file, or if the IDL Acrobat plug-in is not present, IDL displays a default topic. (For more information on the IDL Acrobat plug-in, see About IDL's Online Help System.)
Under Windows, Value is loaded into the help viewer's Index dialog. If Value is omitted, the specified or default file is displayed at its beginning. If the CONTEXT keyword is set, Value should be an integer value (not a string) that represents the context number of the help topic to be displayed; the specified topic will be displayed immediately, bypassing the Index dialog. If the BOOK keyword specifies a PDF file, Value is ignored and the specified file is opened to the first page of the file.
Set this keyword to a string containing the name of the help file to be displayed. If the BOOK keyword is omitted, the default IDL help file is displayed.
reference.pdf. If the Value parameter is not specified, the default IDL help file is onlguide.pdf. Both files are located in the Help subdirectory of the IDL distribution.idl.chm, located in the Help subdirectory of the IDL distribution.If the FULL_PATH keyword is specified, BOOK must specify a complete file path, including the directory specification and file extension for the file. If FULL_PATH is not specified:
Any file specified by this keyword must be in the appropriate format for the viewer being invoked:
.pdf) or an HTML file (.html or .htm)..chm), a WinHelp file (.hlp), a PDF file (.pdf), or an HTML file (.html or .htm). If you specify the file extension, IDL will use the appropriate viewer for that type of file.
| Note |
.chm (Windows only), .hlp (Windows only), .pdf, .html, .htm. You can override this behavior by explicitly specifying the desired file extension.
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 the help topic to be displayed. This keyword is intended for use with user-compiled help files 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.
This keyword is only available on UNIX platforms.
Normally, the string given by the Value argument is folded to upper case before being handed to Acrobat for display. Explicitly set FOLD_CASE=0 to indicate that the string should be handed to Acrobat without modification.
Set this keyword to indicate that 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
This keyword is only available on UNIX platforms.
Set this keyword equal to a page number. Acrobat will open the specified page in the specified PDF file.
Set this keyword to close the Help viewer.
| Note |
Under Unix, if the IDL-Acrobat plug-in is not available for your current platform, ONLINE_HELP will issue warning messages explaining that it is unable to position the document, and that the user will need to manually navigate to the desired information once the Acrobat reader application is running. Set this keyword to prevent these warnings from being issued. On non-Unix platforms, this keyword is quietly ignored.
This keyword is only available on Windows platforms.
Set this keyword to display the Index dialog for the specified help file.
The following keywords are obsolete:
For information on obsolete keywords, See Obsolete Features.
To display an HTML 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.
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. By default, IDL assumes that it should launch the Netscape web browser, and that the netscape command is found 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.
The following example uses the ONLINE_HELP procedure to launch the help viewer to display information on the FFT function:
ONLINE_HELP, 'fft'
This example displays the External Development Guide in PDF format:
ONLINE_HELP, BOOK='edg'
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'
Introduced: 4.0.1
Modified to invoke Adobe Acrobat under UNIX, to invoke the HTML Help viewer by default under Windows, to allow opening of HTML and PDF files on all platforms, and to add the UNIX-only keywords FOLD_CASE and PAGE: 5.6
SUPPRESS_PLUGIN_ERRORS keyword: 6.1
MK_HTML_HELP, ONLINE_HELP_PDF_INDEX, Providing Online Help For Your Application