XHelp is a prototype help browser providing a familiar and easy-to-use interface for the IRAF help system. Other features include on-the-fly conversion of help documents to HTML for display and fully formatted PostScript for hardcopy.
To begin, select a help topic from the top panel, enter a task or package name in the Topic field, or hit the Search button to bring up a panel allowing you to search the help system by keyword.
When invoked with no command line arguments the task starts as a browser and the user is presented with a GUI that has the toplevel CL package menu in the upper navigation window. The main display window below will contain any help page specified in the template parameter or loaded on the command line by specifying the template and file_template parameters. If the search parameter is enabled the template is taken to be a search phrase and the database is searched for tasks matching the keyword and the GUI will appear with the search panel mapped so the user can select the task help to view. When no template is given the main display window will start with the page specified by the home parameter, this can be a user-defined HTML file giving links to specific tasks (see below for details) or if home is empty the display will contain the online help for the task.
The first time the task is run, or whenever the help database is updated,
a quick reference file (specified by the task
quickref
parameter) and package menu file will be created in the user's uparm
directory to speed up help searching and subsequent startups of the task.
Task Parameters
New packages or task help pages are loaded by selecting an item from the package menu list using the left mouse button. If the requested item is a package, the menu listing will change as though the package were loaded in the CL, and the help display panel will contain a listing of the package tasks with a one-line description for each task such as would be seen with a "help <package>" command using the standard task. New items may then be selected using either the menu list or links in the display panel. If the item is a task, the help page for the task will appear in the display panel. In either case new pages may be selected from the menu listing.
Specific help documents may also be requested by entering the task/package name in the Topic text widget above the menu list. As when selecting from the package menu list, items selected this way will cause the menu list to change to the package menu for the parent package if the item is a task (displaying the help page in the display panel) or the package menu if the item is a package (displaying the one-liner package listing in the display panel).
Using the Back button will revert to the previous page in the history list which will either be the previously loaded package or help page. Similarly, selecting the Forward button will move the next page further down in the history list, either button will become insensitive when the end of the list on either end is reached. Selecting the Up button will cause the browser to immediately jump up the previous package, skipping over any help pages that were loaded in between. The Home button will cause the default homepage (either the user-defined page if specified by the task home parameter or the online help) to be displayed. Browsing in this way can also be done using the navigation menu created by hitting the right mouse button while in the main display panel.
Users can also jump to specific pages in the history list using the
History button on the main menubar. The right column of the menu
will indicate whether the item is a task, package, internal link or a text
file. The history list is truncated at about 40 entries in the menu but
the user may work back incrementally by selecting the last item of the
menu, after which the History button will display the previous 40 entries.
The history list may be cleared except for the current page by selecting
the Clear History menu item.
Browsing a Help Document
Once a help page is loaded the middle menubar above the display panel
will change to activate widgets based on the position within the history
list and options available for a particular page. The left-most group
of buttons are the standard navigation buttons described above.
The middle group of buttons contains the Sections and
Parameters buttons which are used to browse within a help document.
The Sections button is a menu listing all of the sections found
within a help page, allowing the user to jump to a specific section
rather than scrolling through the entire document. The Sections
menu is also available using the middle mouse button from the
main display area. The Parameters button is similarly a menu
listing of all task parameter help sections found within the document.
Both or either of these buttons will become insensitive when no section
or parameter information is found in the document.
The right-most group of buttons represent the various help options available
for each page. The default is to get the task help, however help pages
may have an associated source file or sysdoc (e.g. if the task
is a CL script there may be a pointer to the script source itself, or a package
may have a general overview document listed as the system document). Once
a help page is loaded these buttons will change become sensitive if that option
is available, simply select the button to view the option. Selecting the
Files button will bring up a panel listing all the files associated
with a particular help topic. When a help topic is selected and an option is
defined but the file does not exist, the options button will display a yellow
diamond icon even if the button is insensitive, a green icon indicates the
currently selected option. This feature may be disabled by selecting the
"Show missing files" item from the main menubar Options menu.
Searching
Searching the Help Database
Searching the help database is done by selecting the Search button
from the main menubar to bring up the search panel. Users may then enter
one or more keywords into the Topic field at the bottom of the panel
and initiate the search with either a carriage return or hitting the
Search button just beside it. The panel will then show a list of all
tasks and packages which match the search phrase along with a one-line
description of the task. Help pages may be displayed by selecting either the
task or package link with the left mouse button, in both case the package
menu list on the main xhelp window will be updated to list the package
contents allowing other tasks from that package to be selected in the normal
way.
By default the exact phrase entered in the topic window will be used for the search. This can be relaxed by toggling the "Require exact match" button at the top of the panel. For example, to search for all tasks matching either the keyword "flat" or "field" turn off the exact match toggle and the search will return not only tasks matching "flat field" but also any task description containing only one of the words such as the VELVECT task which plots velocity fields.
Searching Within a Document
Within a help document itself one can search for a string by selecting
the Find button from the main menubar to bring up a panel used to
enter the search string. When the text is entered the main display
window will reposition itself and highlight the text found within the
document. Searches can be repeated and will wrap around the document
automatically, searches can be done either forward or backward through
the text and may be case insensitive.
The On-Line Help Panel
The help panel permits the user to view the on-line help document while
XHELP is running. The help panel can be activated by pressing the
help command button in any panel or by selecting the "Help ..." item from
the main File menu. The help panel consists of the the help command
button bar and the help display window which are described below.
HTML files may contain URLs of the form
<a href=[package.]task>url_text</a>
where url_text is the text to appear in the window and the URL itself consists of an optional package and task name delimited by a period. For example, to create a link to the splot task in a document one would use the URL
<a href=onedspec.splot>splot</a>
In this way users can create a homepage which serves as a "bookmark"
file or index of shortcuts to the most commonly accessed help pages.
Loading Files
Text files may be loaded on the command line when starting the task by
specifying the filename and setting the
file_template task parameter. The named file
will be searched for a .help LROFF directing indicating it contains
a help block that will be converted to HTML for display. If no help
block is found the file will be displayed as-is, meaning existing
HTML documents can be loaded and will be formatted correctly.
Once the task is running users may load a file by selecting the Open
File... menu item from the main menubar File menu or the
right-mouse-button menu from within the main display area. This will
open a file browser allowing users to change directories by using the
navigation buttons at the top of the panel, or selecting items from the
leftmost directory listing. Selecting a file on the rightmost list will
cause it to be loaded and automatically formatted if it contains a help
block. The file list may be filtered to select only those files matching
a particular template by changing the Filter box at the top of
the panel. Filenames or directories may be entered directly using the
Selection box at the bottom of the panel.
Saving Files
Once a file has been loaded in the browser it may be saved to disk as
either source (i.e. the original LROFF file if that was converted
for the display, or whatever file is currently displayed regardless of
format), text to save formatted plain text such as that produced
by the standard help task, HTML to save the converted HTML
used in the display, or PostScript to save formatted PostScript of
the document such as that sent to the printer using the Print
button. Not all options will be available depending on the format of the
input text, unavailable options will be insensitive in the GUI.
The Save panel is opened by selecting the Save As... menu
item from the main menubar File menu or the right-mouse-button
menu from within the main display area. The file browser operates the
same as when loading images, the only difference is that file selection
simply defines the filename to be used and does not cause the save to
occur automatically. Users can overwrite existing files by selecting the
Options toggle at the bottom of the panel.
Hardcopy Output
Help pages may be output to any configured iraf printer by selecting the
main menubar Print button to bring up the print panel. Task help
pages will be converted to formatted PostScript and may be sent to either a
printer or saved to disk depending on the selection made in the printer
panel. If the printer name is set to the special value "printer" then
the device named by the CL printer environment variable will be used.
When saving to disk files the default action is to save to a filename whose
name is the task name plus a ".ps" extension. Either of these are
changeable within the GUI as is the default page size to be used when
generating the PostScript.
The main menubar File button can also be used to bring up the file browser in order to save the current document to disk. Help pages may be saved as either the origin LROFF source for the file, formatted text as you would get from the standard help task, HTML as is displayed in the GUI, or formatted PostScript. The choice of formats is dictated by the type of file being displayed (e.g. you cannot save PostScript of a program source).
.hn <name>
.hr <link> <text>
where <name> is the destination name of an internal link, <link> is the URL of the link to be created, and <text> is the text to be displayed in the HTML. The URL syntax is either a '#' character followed by a destination name, a simple task name or package name, or a package.task pair giving a more precise task. For internal links the current document is repositioned so the name is at the top of the display, for task help links new help pages will be loaded in the browser.
These directives are ignored when converting the LROFF to either formatted plain text or PostScript.