\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 <directory>} -- 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{ <keyword>} -- 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 <index dir pathname>} -- specify different index directory for 
Help to use.  This option is mostly of interest to the help maintainers for 
testing purposes.

 \


\bold{-a <help alias file>} --> 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{ <full path to directory: full path to 
directory>}}

\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}
