|
|
Application Programming: Providing Online Help For Your Application |
|
Beginning with IDL version 6.2, IDL's context-sensitive online help system uses a cross-platform help viewer — IDL Assistant — based on the help viewer used by the Qt development toolkit from Trolltech. This section describes how to create your own HTML-format help content for display in the IDL Assistant help viewer. For information on using the viewer, see Getting Help with IDL.
| Note In addition to the context-sensitive online help system, IDL documentation is provided in Adobe Portable Document Format (PDF). See Using the PDF Documentation Set for details. |
While IDL's cross-platform online help system is a convenient way to provide help to users of your IDL application, you can also launch other help viewers using the ONLINE_HELP procedure. See Using Other Online Help Viewers for details.
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:
<IMG> tag. See Creating Help Content below.
.adp) file that defines both the hierarchical structure of the documentation (the table of contents) and its keyword index. See Creating an Assistant Document Profile.
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.
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.
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 for additional details related to how IDL interprets the Value argument.
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.
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.
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>
Elements of this type do not contain an element value, and do not need to be closed.
All of the content of the .adp file is enclosed in an <assistantconfig> element.
Elements of this type contain <profile> and <DCF> elements.
When creating content for the IDL Assistant help viewer, set the version attribute to the value "3.3.0":
<assistantconfig version="3.3.0">
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.
Elements of this type contain <property> elements.
Each <property> element defines a value used to configure the help viewer application.
The element value is a text string. Each element must include a name attribute with one of the attribute values listed below.
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>
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>
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. |
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.
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. |
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>
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.
Elements of this type contain <section> elements.
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.
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">
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.
Elements of this type contain <section> and <keyword> elements.
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.
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>
A <keyword> element defines an entry in the help system's keyword index. Keyword index entries are displayed in the Index tab.
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.
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>
The files described in this section are not required for your help system to function, but may be useful.
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.
The TopicNotFound.html file is displayed when the Value argument to the ONLINE_HELP procedure is supplied, but the specified file is not found. You can create your own version of this file, or copy the TopicNotFound.html file from the help/online_help subdirectory of the IDL installation. See Displaying Help Topics below for additional information.
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:
myapp.adp file in a directory contained in IDL's help path. If it cannot locate the .adp file, ONLINE_HELP exits with an error.
myapp.adp for a file named INTERESTINGTOPIC with the extension .html or .HTML. If IDL finds this file, it is displayed in the help viewer's main pane, and the search ends.
myapp.adp for a file named InterestingTopic with the extension .html. If IDL finds this file, it is displayed in the help viewer's main pane, and the search ends.
TopicNotFound.html in the help viewer's main pane. This file explains to the user that there is no file that matches the Value argument.
In general, your end-users should never see the TopicNotFound.html file, because you have control over the strings placed in the Value argument to the ONLINE_HELP procedure. You should, however, feel free to either create your own TopicNotFound.html file or copy the version included in the help/online_help subdirectory of the IDL distribution.
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 and help/online_help subdirectories 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.
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.
IDL Online Help (March 06, 2007)