From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- lib/scr/help.html | 586 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 586 insertions(+) create mode 100644 lib/scr/help.html (limited to 'lib/scr/help.html') diff --git a/lib/scr/help.html b/lib/scr/help.html new file mode 100644 index 00000000..46f584d7 --- /dev/null +++ b/lib/scr/help.html @@ -0,0 +1,586 @@ + + +IRAF Help GUI +

Welcome to IRAF Help GUI V1.0

+

+Help is a prototype GUI 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. +

+

+ +

Table of Contents

+ + + + +

Introduction

 +The Help GUI task is a front-end to the IRAF +help +task which provides on-the-fly conversion of help documents to HTML for +presentation in the GUI or formatted PostScript for hardcopy. +Help pages may be loaded on the command line, through use of a +file browser, or by navigating the help databases using a familiar CL +package menu scheme. It also features a search capability similar to the +references +task and a complete history mechanism. +

+When invoked with no command line arguments (and the appropriate +device parameter setting of "gui") 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 LROFF source file specified in the +template +parameter or loaded on +the command line by specifying the +template +and enabling the +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

+ + +

Navigating the IRAF Help System

 + + When run as a browser, Help works very much like any WWW browser. +The top panel is a list widget that will always contain a CL package listing, +at startup this will be the toplevel "Home" package menu one would see +when first logging into the CL containing the core system packages, NOAO +package, and any site-specific external package, or in the case of starting +with a specific task it will be the parent package for the task. +Additionally, system documents for the os +HSI routines and the imfort and +math +interfaces will be available in the Home package although +these are programmatic interfaces and not tasks which can be executed. +

+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 help 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. +

+

+
The Help Command Button Bar +
The command button bar contains the following command buttons. +

+ +

+
The Back Command Button +
Pressing the Back command button moves backwards through the +previously visited links. +

+

The Forward Button +
Pressing the Forward command button moves forward through the +list of visited links. +

+

The Home Button +
Pressing the Home command button sets the help display window to +the top of the help document. +

+

The Dismiss Button +
Pressing the Dismiss command button deactivates the help panel. +

+

+
+ +The bottom of the help panel contains a text search entry widget allowing +for text searches of the documentation along with options for searching +in a forward or backward direction, and case sensitivity. When a search +phrase is entered the help document will be repositioned to the next +occcurrance of the search string if found, otherwise a dialog box will +appear to say the string was not found. Searches will wrap around the +document automatically. + + +

User-Defined Homepages

 +By default Xhelp will start with the online help page displayed in the +main help window. The user can change this by setting the task home +parameter to be a path to any valid file. This file may be plain text, a +help document in LROFF format which will be converted to HTML for display, +or a native HTML document. +

+HTML files may contain URLs of the form +

+

+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 +

+

+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). + +

+

LROFF Extensions for HTML

 +To better support HTML links within documents and to other help pages two +new directives have been added to the LROFF text formatter. These are +.hr to specify a link (an HTML HREF directive) and .hn +to specify a name (an HTML NAME directive). The syntax for these are +as follows: +
+        .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. + + + -- cgit