\begindata{text,538535312} \textdsversion{12} \template{help} \define{global } \chapter{Help: A User Assistance Program } \section{What Help is }\leftindent{ The \italic{Help} program finds and displays information about Andrew and its programs as well as about the UNIX operating system. }\section{Starting Help} \leftindent{ Help can be started by typing \leftindent{help \italic{keyword}} in the command window and pressing the Enter key. The command window is usually an xterm or typescript window. \italic{Keyword} is a word about which you would like to see more information. For example, to see the help information about printing documents on Andrew, you can type \leftindent{help printing} and the Help window will display information about printing. If you supply a keyword for which no help is available when you start Help, the Help window opens and tells you \leftindent{Sorry, no help available on \italic{keyword.}} Click in the button that says \bold{\italic{Continue}} to display the document that would appear if you had typed help without a keyword. \ } \section{Getting More Help }\section{\ }\leftindent{Once you have a Help window open, you may wish to get help on different keywords and see information about them. There are several ways to have Help show you more information. \bold{Using the Overviews and Programs panels. } }\leftindent{The scrollable Overviews and Programs panels provide an easy way to find help about common tasks and programs on Andrew. Point the cursor at a name in either the Overviews or Programs panel and click with the left mouse button to see the information associated with it. \ \leftindent{Note that the Programs listing is only a partial listing of all the programs that are available on Andrew. You can see a list of all the programs on Andrew by choosing\bold{ Expand Programs List} from the pop-up menus. The list of all programs will appear in the \bold{Programs} panel.} \bold{Clicking on phrases in the help file.} If you see a word that is boxed, (like \helptopic{printing} ), there is probably more help available on that word. To see help on a boxed word, simply click with the left mouse button on the word. Note that at the very end of many help files there is a section called "Related tools" that contains boxed words about which there is more information. If you instead click with the right mouse button, the new help topic will appear in a new window. The help file you were reading will remain visible. You can open as many windows on different topics as you wish, and can delete windows using \bold{Delete This Window} from the \italic{Window} menu. Note, though, that if you \bold{Quit} from any window, they will \italic{all} disappear. \bold{Using the Menus.} If you want help on a topic that is not listed in the Overviews or Programs panel, and doesn't appear right in front of you as an italicized word, you can supply Help with a new keyword by choosing \bold{Show Help on ...} from the front pop-up menu card. The following prompt appears: Enter a keyword about which you want more help: Type the keyword and press Enter. \ If you want to bring a new help file up in a new window, leaving the original help file on the screen, use instead the \bold{Show Help on ...} menu option on the \italic{Window} menu card. Again, remember that you should use the \bold{Delete This Window} option to remove single windows, and \bold{Quit} to remove all of them. \ \bold{Seeing additional files when there are multiple files. } Sometimes there are several files associated with one keyword. You can tell if this is the case by the word "(more)" in Help's titlebar. To see the next document, choose \bold{Show More Documentation} from the pop-up menus. \bold{Help requests from Typescript. } Finally, you can supply an existing Help window with new keywords by typing "help keyword" in the Typescript window. When you type "help keyword" in the Typescript, the help request is sent to the existing Help window if there is one, instead of starting a new window. }\ \section{Pop-up menu meanings }\leftindent{ Here are the pop-up menus for Help and their meanings: \italic{Front menu} \leftindent{\bold{Copy:} (This menu item only appears if there is a selected region in the Help window.) Makes a copy of the selected text. The text you copied most recently can be pasted into any scrollable window using\bold{ Paste} from the pop-up menus. \ \bold{Show Help on ...: }Allows you to type in a keyword for which Help will search. The following prompt will appear in the message line: \leftindent{Enter a keyword about which you want more help:} Type the word and press the Enter key. \bold{Show\bold{ }}\bold{Help on Selected Word: }Searches for a help document about the selected word. You can only get help on single words or hyphenated words (no multi-word phrases). \ \bold{Show Changes:} (This menu item only appears if there is a change document available.) Displays the "change document" associated with the programs whose help is currently displayed. If there has been a recent release of the program, there may be a change document detailing user-visible changes. \ \bold{Show Tutorial:} (This menu item only appears if there is a tutorial available.) Displays a tutorial associated with the program whose help is currently displayed. \ \bold{Show More Documentation:} (This menu item only appears if another help document or man page is available.) Displays other help documents about the same keyword. Sometimes more than one program exists by the same name, so there are sometimes several help or man entries available for a given keyword. \bold{Send Comment on Help:} Lets you suggest improvements to the Andrew Help system. When you choose this menu item, an addressed SendMessage window appears. Type your message and choose \bold{Send/Post} from the pop-up menus in the SendMessage window. \ \bold{Quit: } Quits the Help program and closes the window. If more than one Help window has been opened, they will all quit. }\italic{Search menu} For more information about how searching works in Andrew programs such as Help, see the \italic{searching} help document. \ \leftindent{\bold{Forward:} Searches in the help document from the current cursor position forward. After you choose this option, Help puts the "Search for :" prompt in the message line at the bottom of the window. Type the string of letters or numbers that you want to search for and press the Enter key. If any of these characters are in the search string \leftindent{[ ] * . \\} precede each of them with a backslash (the last character in the set above). \ \bold{Backward:} Searches in your document from the current cursor position backward. Specify what you want to search for in the same way as for the\bold{ Forward} option. \bold{Search Again: } Searches for the same string and in the same direction as the search you did most recently. This operation is helpful if you want to search for several different occurrences of the same word. Specify what you want to search for in the same way as for the \bold{Forward} option. }\ \ \leftindent{\bold{Search Overviews:} Searches forward from the currently selected item in the Overviews panel. Specify what you want to search for in the same way as for the\bold{ Forward} option. The panel scrolls to bring what you are searching for into view, but does not select it. \bold{Search Programs:} Searches forward from the currently selected item in the Programs panel. Specify what you want to search for in the same way as for the\bold{ Forward} option. The panel scrolls to bring what you are searching for into view, but does not select it.} \italic{Print menu} \leftindent{\bold{Set Printer:} Sets the default printer for documents queued for printing from with Help. Help prompts you for the name of a printer to use instead of your usual default.} \leftindent{\bold{Print This File:} Queues the currently-displayed document for printing.} \italic{Other menu} \leftindent{ \bold{Filter Programs Panel:} This will prompt you for a string. Help will then replace the contents of the Programs panel with file which have the string as part of their name. \ \bold{ReFilter Programs Panel:} (This only appears if the Programs panel is currently filtered.) This will prompt for a string and re-filter the filtered panel like \bold{Filter Programs Panel}. \bold{Restore Programs Panel:} (This only appears if the Programs panel is currently filtered.) Restore the Programs panel to the state it was in before any filter operations were done. \bold{Add Search Directory:} Prompts for a full pathname to a directory, and adds that directory to the list of directories in which Help will search for files. \bold{Make Bookmark:} Choosing this menu item makes an entry in the History panel marking the current file and the place in the file you are currently viewing. Clicking on that entry in the History panel will return you to the exact spot where the file was when \bold{Make Bookmark} was chosen. } \italic{Panels menu} \leftindent{\bold{Show/Hide Panels: } Exposes or hides the panels at the right of the Help window. See the section on Preferences in this document for information about the help.showpanels preference, which allows you to have the panels always hidden or always shown on startup. They are exposed by default. \bold{Expand/Shrink Programs List:} Expands or shrinks the list of programs in the Programs panel. When expanded, the Programs panel contains a list of all the available documents on the system, including the files available in the user-added Search Directories. When shrunk, the panel contains a smaller list of the more commonly used Andrew programs. \bold{Show/Hide Overviews:} Exposes or hides the Overviews panel at the right of the Help window. The Overviews panel contains commonly used help topics that are of general interest. See the section on Preferences in this document for information about the help.showoverviews preference, which allows you to have the overview panel always hidden or always shown on startup. It is exposed by default. \bold{Show/Hide Programs:} Exposes or hides the Program List panel at the right of the Help window. The Programs panel is a list of help topics about programs that can be run on Andrew. This list can either be condensed or complete. See the entry on Expanding the Programs List in this section. See the section on Preferences in this document for information about the help.showprograms preference, which allows you to have the history panel always hidden or always shown on startup. It is exposed by default. \bold{Show/Hide History:} Exposes or hides the History panel at the right of the Help window. The history panel contains the names of all keywords used during the current Help session. Clicking on any entry in this panel allows you to easily return to the help on that topic. See the section on Preferences in this document for information about the help.showhistory preference, which allows you to have the history panel always hidden or always shown on startup. It is hidden by default. }\italic{Window menu} \leftindent{\bold{Show Help On...:} functions the same as the \bold{Show Help On...} menu item, except that after entering the help topic, the help file will appear in a new window. }\leftindent{ \bold{Show Help on Selected Word:} functions the same as the \bold{Show Help on Selected Word} menu item, except that Help will put the file for the selected topic in a new window. \bold{Delete This Window: } deletes only the window that the option is chosen from. To quit Help, use \bold{Quit} from the front menu card. }} \section{Options to Help }\leftindent{ \bold{-h }or\bold{ -x} -- show a brief usage statement of help options \bold{-m} -- 'more' mode, for use with CRTs. Formats each help document for display on a CRT and uses \helptopic{more}\italic{ }to present them. If more than one help entry is found on a keyword, you are prompted for which entry you wanted to see. Help is run with "-m" by default when it is invoked from outside a window manager. \ \bold{-s } -- search the named directory in addition to the system directories. This option allows you to put help documents into a personal directory and then have Help find those help documents when it starts. Using "-s" slows the startup time of Help by adding more directories to search. See the section on Preferences in this help document for information about the help.searchpath preference, by which you can cause every Help window that you start to search a directory that you name. \ \bold{- l}\bold{ } -- does not open a Help window, but prints out a list of all the files that are found for the keyword. \bold{-new} -- force creation of a new window, rather than sending the help file to an old window. \bold{-i } -- specify different index directory for Help to use. This option is mostly of interest to the help maintainers for testing purposes. \ \bold{-a } --> specify a different help aliases file for Help to use. This option is mostly of interest to the help maintainers for testing purposes. \ \bold{-e} -- don't show help on any topic when starting up. Start with an empty window. \bold{-o} -- (used only when Help is used from a terminal) Help will prompt after showing each file whether or not to print the file last displayed. If a file is printed, it will be printed on the users' default printer. } \section{Preferences} \leftindent{The following preferences are available in Help. They are shown here with their default values typed in. You do not need to put these preferences into your preferences file unless you want to change the default values that are shown. You can mix uppercase and lowercase letters in preference entries if you wish, although you cannot mix case where a directory or pathname is required, the pathname must be and exact match of the actual pathname to be used. \bold{help}\bold{.searchpath:\italic{ }} \indent{Provides a path of directories for Help to search in addition to the standard help directories when it starts. By default, only the system directories are searched. This preference allows you to put help documents into a personal directory and make them available to a small group of users in addition to the system help file. For example, the Computer Club has documentation for its programs in /afs/andrew.cmu.edu/usr0/cl0x/man. To have Help always look in this directory for help files, you could put: help.searchpath: /afs/andrew.cmu.edu/usr0/cl0x/man so that whenever they start Help, they will see the information in that directory as well as the regular help files. You can add as many directories as you like to help.searchpath. Be sure to separate them with colons (:) if you add more than one. Using this preference slows the startup time of Help a little; the more directories you add, the slower Help will be when it starts. } \bold{help.showpanels: \italic{on}} \indent{When set to "off," causes the Overviews and Programs panels in the Help window to be hidden when you start Help. The default is "on," causing the panels to be shown when you start Help. \ } \bold{help.showoverviews: \italic{on}} \indent{When set to "off", Help will not display the Overviews Panel when it starts up } \bold{help.showprograms: \italic{on}} \indent{When set to "off", Help will not display the Program List panel when it starts up. } \bold{help.showhistory: \italic{off}} \indent{When set to "on," Help will display the History panel when it starts up } \bold{help.expandedlist: \italic{off}} \indent{When set to "on," Help will start up with the Programs panel containing a full list of programs available, instead of the default condensed list. Be aware that setting this preference to "on" will slow down Help's startup time. } }\section{Related tools} Select (highlight) one of the italicized names and choose "Show Help on Selected Word" from the pop-up menu to see the help document for: \ \leftindent{\helptopic{Andrew} (the Tour) \helptopic{searching}\italic{ }\helptopic{help-keys}}\italic{ } \begindata{bp,538505984} \enddata{bp,538505984} \view{bpv,538505984,1,0,0} Copyright 1992 Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538535312}