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 topic displayed.
Note: This procedure is intended for use in user-written routines. The ? command, which is a shorthand for the ONLINE_HELP procedure, is intended for use at the IDL command line.
Use the ONLINE_HELP procedure to display help content in the following formats:
- HTML (displayed in the IDL help system)
- Adobe Portable Document Format (PDF)
- Microsoft Windows HTML Help (*.chm files)
- Microsoft Windows Help (*.hlp files)
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 IDL help viewer.
ONLINE_HELP, BOOK='myfile.html'
Syntax
ONLINE_HELP [, Value] [, BOOK=‘filename’] [, /FULL_PATH] [, TITLE = 'title']
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:
- If neither the BOOK keyword nor the Value argument is specified, IDL will display the IDL online help system’s home page.
- If the BOOK keyword is not specified, IDL will search the IDL system for a topic whose name matches the help system.
- If the BOOK keyword is specified, Value will be interpreted as described in the table following the description for the BOOK keyword, below.
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 IDL help system for a topic whose name matches Value. If neither the BOOK keyword or the Value argument is specified, 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:
|
Extension |
File Type |
Behavior |
|
.html.htm
|
HTML |
Opens the specified HTML file in IDL's help viewer. If the Value argument is present, it is treated as an anchor value and appended to the URL for the specified HTML file. In most cases, this will cause the browser to position the file content so that the specified anchor is at the top of the viewing window. If the anchor is not present in the HTML file, the browser generally ignores it quietly.
Note: See Displaying HTML and PDF Files under UNIX for additional information.
|
|
.chm
|
Windows HTML Help
|
Opens the specified Windows HTML Help file. If the Value argument is present, the Index tab of the HTML Help viewer is positioned to display the closest matching value. See also the CONTEXT keyword.
|
|
.hlp
|
Windows Help |
Opens the specified Windows Help file. If the Value argument is present, the Index tab of the Help viewer is positioned to display the closest matching value. See also the CONTEXT keyword.
|
|
.pdf
|
Acrobat |
Opens the specified PDF file in the system default PDF viewer. The Value argument is quietly ignored.
Note: See Displaying HTML and PDF Files under UNIX for additional information.
|
|
None |
Any type |
Searches the directories specified by the !HELP_PATH environment variable for a file whose base name matches the specified value, in this order: .adp, .chm (Windows only), .hlp (Windows only), .pdf, .html, .htm. The first file found is opened and the Value argument interpreted as described by this table.
Note: Topics in the IDL help system will not be found by this mechanism.
|
Note: If the FULL_PATH keyword is specified, BOOK must specify a complete file path, including the directory specification and file extension for the file.
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.
TITLE
Set this keyword to a string to give the IDL Help a unique name. If no name is given, the default is "IDL Help."
Displaying HTML and PDF Files under UNIX
To display an HTML or PDF file on a Windows system, IDL 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 Mac 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. 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 Mac 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.
Version History
|
4.01 |
Introduced |
|
5.6 |
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
|
|
6.1 |
Added SUPPRESS_PLUGIN_ERRORS keyword
|
|
Pre-6.2 |
Deprecated HTML_HELP keyword
|
|
6.2 |
Deprecated the FOLD_CASE, PAGE, SUPPRESS_PLUGIN_ERRORS, and TOPICS keywords
|
|
7.0 |
Modified behavior when BOOK keyword is not specified; IDL now searches only in the IDL help system rather than searching the directories in !HELP_PATH.
|
|
8.0 |
Obsoleted the QUIT keyword.
|
|
8.2 |
Added the TITLE keyword.
|
See Also
MAKE_RT, MK_HTML_HELP