Using Other Online Help Viewers
You can use the ONLINE_HELP procedure to display help files in several formats. The type of help file or files you choose to create will depend on the platforms on which your IDL application will be used, and on your own preferences.
IDL Assistant Help Systems
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.
The process of creating help systems for that use the IDL Assistant is somewhat complex. See Using the IDL Assistant Help System for complete details.
Microsoft Windows Help
There are currently two Windows online help formats in wide use: WinHelp and HTML Help. WinHelp is the older of the two, and many applications still provide help in this format, which can be distinguished by the file extension ".hlp". HTML Help is the newer format, and provides (among other things) the ability to include links to documents in various formats, both local and network-based. HTML Help files use the file extension ".chm". Viewers for both types of online help are included in all relatively current versions of Windows, and IDL's ONLINE_HELP procedure will invoke the correct viewer for either type of file.
Creating Windows Help Files
Microsoft Windows help files are relatively easy to create. Files in a specified format (the Rich Text Format, (RTF) for WinHelp, or a wider variety of formats for HTML Help) are compiled with a help compiler from Microsoft. The help compiler is part of the Windows Software Developer's Kit, and is now included in several Microsoft programming products, including the Visual C++ development environment. The help compiler may also be available from the Microsoft Web site or other Microsoft online software libraries at little or no cost.
It is beyond the scope of this manual to discuss the preparation and compilation of Windows help files. Microsoft provides useful information about its help-system products as part of the Microsoft Developer's Network; try searching the MSDN site at http://msdn.microsoft.com with the search term "HTML Help" or "WinHelp". There are also numerous third-party books on creating Windows help systems available.
Calling Windows Help Files
To call a Windows help file of either type from within IDL, use the ONLINE_HELP procedure. Specify the name of your help file using the BOOK keyword, and optionally specify a search term in the Value argument. Alternatively, you can specify a context number in the Value argument and include the CONTEXT keyword. See "ONLINE_HELP" (IDL Reference Guide) for details.
Depending on where your application and its help files are installed, you may also need to specify the full path to the file and the FULL_PATH keyword.
Example 1
Suppose you have created an HTML Help file named myapp.chm to accompany your IDL application. Use the following call to open the HTML Help viewer and load the search term "controls" into the Index dialog:
where path is the full path to the file myapp.chm.
Example 2
Suppose you have created a WinHelp file named myapp.hlp and placed it in the Help subdirectory of your IDL installation. If you know that the context number of the topic you wish to display is 250, use the following call to open the WinHelp viewer to the correct topic:
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: .chm (Windows only), .hlp (Windows only), .pdf, .html, .htm. See Paths for Help Files for details on setting the help path.
Cross-Platform Issues
Windows help files (of either format) are viewable only on Microsoft Windows platforms. If your IDL application will be available on UNIX platforms as well as Microsoft Windows platforms, you have several options:
- Create help content suitable for use by the cross-platform IDL Assistant help viewer. See About IDL's Online Help System for details on creating help content that will display in IDL Assistant.
- Create separate help files (one in Windows Help format, one in PDF or HTML format) and issue the appropriate call to ONLINE_HELP based on the current platform. If you name the files with the same base name (but with different file extensions), IDL will automatically select the correct file for the platform.
- Create a single help file in PDF or HTML format, and caution your users that they must have a the appropriate viewing application installed in order to use your help file. In addition, UNIX users must ensure that the viewing application is properly configured for use by IDL, as described in Displaying HTML and PDF Files under UNIX under "ONLINE_HELP" (IDL Reference Guide).
Portable Document Format Files
You can use the ONLINE_HELP procedure to display a PDF file on any system that has a PDF-display application installed.
Note
IDL launches a stand-alone version of the PDF viewing application. Files are not displayed in the Windows help viewer or any other browser application.
Creating PDF Files
To create PDF files for use with IDL's online help system, you will need an application that allows you to author PDF files or convert files in other formats to PDF. Most commonly, source files are created with a text-editor, word-processor, or other document-production program, printed to a PostScript file, and run through a program that distills the PostScript into PDF. Adobe's commercial Acrobat package includes the Acrobat Distiller, which provides a convenient GUI interface to the distillation process. Other third-party software to distill PostScript files into PDF is also available; GhostScript (www.ghostscript.com) is one freely available alternative.
It is beyond the scope of this manual to discuss creation of PDF files in detail; consult the documentation for your PDF authoring system or distilling software for details.
Calling PDF Files
To call a PDF help file from within IDL, use the ONLINE_HELP procedure. Specify the name of your PDF file using the BOOK keyword. Depending on where your application and its help files are installed, you may also need to specify the full path to the file and the FULL_PATH keyword.
See "ONLINE_HELP" (IDL Reference Guide) for details.
Example 1
Suppose you have created a PDF file named myapp.pdf to accompany your IDL application. Use the following call to open the PDF viewer and display the first page of the file:
where path is the full path to the file myapp.pdf.
Example 2
If the myapp.pdf file is located in one of the directories included in IDL's !HELP_PATH system variable, you do not need to include either the .pdf extension or the FULL_PATH keyword:
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: .chm (Windows only), .hlp (Windows only), .pdf, .html, .htm. See Paths for Help Files for details on setting the help path.
Cross-Platform Issues
If you intend to use PDF files to supply online help for your cross-platform application, you should caution your users that they must have a the appropriate PDF viewing application installed in order to use your help file. In addition, UNIX users must ensure that the viewing application is properly configured for use by IDL, as described in Displaying HTML and PDF Files under UNIX under "ONLINE_HELP" (IDL Reference Guide).
HTML Files
You can use the ONLINE_HELP procedure to display an HTML file on any system that has a Web-browser installed. On UNIX systems, the browser's executable file must also be in a directory included in the PATH environment variable.
Creating HTML Files
It is beyond the scope of this manual to discuss HTML authoring in detail. Use any technique you are comfortable with to create HTML files for display in a normal Web browser.
Note
You can use the MK_HTML_HELP procedure to create HTML-formatted documentation for your application from standard IDL documentation headers. See "MK_HTML_HELP" (IDL Reference Guide) for details.
Calling HTML Files
To call an HTML file from within IDL, use the ONLINE_HELP procedure. Specify the name of your HTML file using the BOOK keyword. Depending on where your application and its help files are installed, you may also need to specify the full path to the file and the FULL_PATH keyword.
See "ONLINE_HELP" (IDL Reference Guide) for details.
Example 1
Suppose you have created an HTML file named myapp.html to accompany your IDL application. Use the following call to open the default Web browser and display the file, positioned to the HTML anchor tag anchor1:
where path is the full path to the file myapp.html.
Example 2
If the myapp.html file is located in one of the directories included in IDL's !HELP_PATH system variable, you do not need to include the .html extension or the FULL_PATH keyword:
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: .chm (Windows only), .hlp (Windows only), .pdf, .html, .htm. See Paths for Help Files for details on setting the help path.
Cross-Platform Issues
If you intend to use HTML files to supply online help for your cross-platform application, keep the following things in mind:
- IDL does not require that a Web browser be installed. While it is unlikely that you will encounter systems that do not include a Web browser, you may wish to inform your users in advance that your application uses a Web browser to supply help.
- On UNIX systems, it may be necessary to modify IDL's default HTML browser configuration script to use a locally-preferred browser. See Displaying HTML and PDF Files under UNIX under "ONLINE_HELP" (IDL Reference Guide) for details.
- Different browsers contain different display engines, and may display HTML in different ways. This is especially true if you use features that have only recently been added to the HTML specification. Check for display issues using as many browsers as you reasonably can.
