\begindata{text,17298436}
\textdsversion{12}
\template{default}
\define{global
}
\define{programexample
menu:[Region~4,ProgramExample~13]
attr:[LeftMargin LeftMargin Inch 32768]
attr:[Justification LeftJustified Point 0]
attr:[Flags NoFill Int Set]
attr:[Flags KeepPriorNL Int Set]
attr:[Flags KeepNextNL Int Set]
attr:[FontFace FixedFace Int Set]
attr:[FontFamily AndyType Int 0]}
\define{formattingnote
menu:[Region,FormattingNote]
attr:[Flags PassThru Int Set]
attr:[Flags NoFill Int Set]
attr:[Flags KeepPriorNL Int Set]
attr:[Flags KeepNextNL Int Set]}
\define{footnote
attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}
\chapter{1 Maintainer's Guide to the Andrew Help System}
Last updated: 1/25/93
This document is written for people maintaining the Andrew Help System.
Although the document is designed to be useful with any Andrew Help
System,
it contains specific references to the Help System in place at Carnegie
Mellon
University, explaining some of the needs encountered, and how the Help
System
was configured to meet them.
\smaller{Note: If you have worked with the ATK help system in the past,
you
should note that some things have changed as of Jan. 1993. The procedures
for
customizing help's behavior for your site have changed; they are now more
in
line with Andrew's policy that you should only have to make changes to
your
site directory. See sections 1.1 to 1.3 for details.
}
There are several things Help maintainers need to concern themselves
with:
Specify directories to be searched
Map keywords to help files
Change the contents of the Programs and Overviews panels
Customize the Help program
Add help documents
Update help documents
Change the appearance of help documents
Understand how Help works
These activities are explained in this document. If you are using EZ to
read
this, you can use the interactive table of contents by choosing
\bold{Table of
Contents} from the \italic{Page} menu card.
\section{1.1
Specify directories to be searched}
You specify which directories Help searches (its "search path") by
creating a
help index. The index directory was designed to speed up Help's startup
time.
It is a collection of pointers to all the help files that Help uses when
it
tries to locate a file in response to a keyword. Notice that the index
directory has nothing to do with indexing in a textual or keyword sense.
Help will not run without an index. This is a list of all the help files
and
man pages that help can find. The index is usually installed in the
directory
/usr/andrew/lib/help.index/, although Help can be told to find it in a
different location (see the Customization section). It is created using
the
program \typewriter{mkindex}.
The indexing process should be run whenever you add or remove a file from
any
of the directories it indexes. Updating a file does not disturb the
index.
By default, the Imakefile in andrew/helpindex runs \typewriter{mkindex}
using
a standard input file, which can be found in
andrew/helpindex/default.idx.
This indexes all of the ATK documentation files, and all of the man pages
in
/usr/man.
If you want help to find files in other directories, you'll have to
create
this file yourself. (See the next section for information about the
syntax.)
Put it in your andrew/site directory under the name common.idx. The next
time
you compile or install ATK, the help index will be created using
andrew/site/common.idx instead of andrew/helpindex/default.idx.
If you are installing ATK on several types of machines, you may want
different
directories indexed on each one. You can do this by putting the
\typewriter{mkindex} input file into the site directory under the name
\{SYSTYPE\}.idx instead of common.idx. (For example, pmax_ul4.idx,
rs_aix32.idx, and so forth.)
If you install both \{SYSTYPE\}.idx and common.idx in your site
directory,
both will be used. (They'll be concatenated together when
\typewriter{mkindex}
is run on that system type.)
\subsection{1.1.1 Creating your own mkindex input file}
\typewriter{Mkindex }takes an input file which specifies the directories
mkindex will use to create an index, and thus delineates what the default
system is to the user. The input file can contain the following
commands:
\smaller{\typewriter{# comment
dir
actual-directory-name
include
key
link-directory-name
filename
keyword
filename
}
}The white space between the words on each line can be any number of tabs
or
spaces.
Here is an explanation of the commands:
\indent{#
\italic{comment}
\indent{Any line beginning with "#" is a comment and is ignored.}
dir
\italic{actual-directory-name
link-directory-name}
\indent{This command tells mkindex to index the files in
actual-directory-name, and record the path to those files as starting
with
link-directory-name. If either actual-directory-name or link-directoryname
are "man" (as in /usr/man) mkindex will recurse down any subdirectories
named
"man[1-8,n,o,l,p,x]". These man extensions can be changed in
andrew/atk/help/src/config.c.
If you look at andrew/helpindex/default.idx, you'll see that it contains
the
line
\typewriter{dir DESTDIR/help DESTDIR/help}
In the Imakefile, before mkindex is run, any occurence of DESTDIR (all
upper-case) is replaced with the value of DESTDIR -- that is, the
directory
where ATK is being installed. The line quoted above will therefore index
all
of the ATK help files. You can use this construct in the mkindex input
files
that you write.
At Carnegie Mellon, /usr/man is a link to
/afs/andrew/machinetype/usr/man, so
mkindex's input file contains the line:
\typewriter{dir /afs/andrew/machinetype/usr/man /usr/man
}where machinetype is the name used to refer to a specific machine's
system-specific directories.}
include
\italic{filename}
\indent{This line tells mkindex to read in the file filename as more
mkindex
commands. At Carnegie Mellon, this facility is used to allow different
indices on different machine types to all include a set of common system
directories.
}
key
\italic{keyword
path-to-file}\italic{
}}\indent{\indent{This line tells mkindex to explicitly use keyword as an
alias for the file specified. This alias functions identically to
aliases in
the help.aliases file, as described in the section Aliases.}
}\subsection{1.1.2
Rebuilding the help index}
The help index is built from scratch every time you compile and install
ATK.
If you want to rebuild it (either because you've added or removed files
from
the indexed directories, or because you've changed the
\typewriter{mkindex}
input file itself), the easiest thing to do is cd to the andrew/helpindex
directory and type "make Install".
If you want to run \typewriter{mkindex} by hand, you can do it as
follows:
\typewriter{\indent{\smaller{mkindex -v input-filename target-directory}
}}Input-filename is the file containing indexer commands. Targetdirectory is
the name of the directory into which the index files will be placed.
specifies "verbose" mode.
-v
The target directory must exist before \typewriter{mkindex} is run.
\bold{NOTE: all files in the target directory are removed before the
index
is created. For this reason, do not specify a directory containing help
files
as the target directory.
}
A caveat: the hack that changes DESTDIR into the actual destination
directory
name is done in the Imakefile, not in \typewriter{mkindex}. If you want
to run
\typewriter{mkindex} by hand, you should not put DESTDIR in the input
file.
The new index can be used with the -i switch to Help, as described in the
"Where does Help find information" section on Understanding Help.
\subsection{1.1.3 Indexing at CMU}
At Carnegie Mellon, creating a Help index is a somewhat
baroque\footnote{\
\begindata{fnote,17848876}
\textdsversion{12}
Or possibly just broke.\
\enddata{fnote,17848876}
\view{fnotev,17848876,2,0,15}} procedure. The mechanism described above
(common.idx, \{SYSTYPE\}.idx, and all that) is not used.
Because there are multiple machine types on campus, and different man
pages
for each sys-type (not just in terms of content), there must be separate
indices constructed for each different sys-type. So, different index
input
files reference directories like
/afs/andrew/rt_r3/usr/man/man1
There are, however, many files which are not machine-specific which
reside in
"common" directories, like
/afs/andrew/common/usr/andrew/help
These files are also included in building the separate indices.
The Help indices are generated automatically via a cron job each evening
on a
secure machine. Because the indices for different machines are created
on one
machine, the input and output files must specify directories by complete
pathnames. In other words, it isn't enough to give
/usr/andrew/lib/help.index as an output directory; the full pathname,
/afs/andrew/rt_r3/usr/andrew/lib/help.index must be used. The explicit
use of
full pathnames is accomplished via a cascade of small scripts that call
\typewriter{mkindex} with the appropriate input files, put the indices in
the
appropriate directories, and mail a nightly post of the output to
andrew.daemons.help.
The start of the script cascade is in ~hm99/index/makeandyindex for the
/usr/andy indices.
\section{1.2
Mapping keywords to files}
Mapping keywords to files is referred to as "aliasing." Aliases are
useful in
several ways: they allow the Help maintainers to anticipate user's
requests
and map them to specific documents (like mapping "sendmessages" to
"sendmessage"), they allow maintainers to map multiple keywords to the
same
file (like mapping "lset" and "arb" to the "adew" document, where those
concepts are discussed), etc.
Many help aliases are defined in the ATK source tree. These are always
installed when ATK is installed. There is also a standard list of aliases
defined in andrew/helpindex/help.alias; these are also always installed.
There are two ways that you (the Help maintainer) can add aliases to the
Help
system.
\indent{1) Use the "key" command in the input file to
\typewriter{mkindex}, as
described in the previous section on Creating a Help Index. These
aliases
will not take effect until the next time the help index is rebuilt.
2) Create a help.alias file and put it in your andrew/site directory. The
next
time you rebuild the help aliases, those aliases will be installed along
with
all of the standard ones.
}Like the help index, the help aliases are rebuilt when you "make
Install" in
the andrew/helpindex directory. The final alias list (the one that help
actually uses) is installed in /usr/andrew/help/help.aliases by default.
(The
name and location can be changed; see the section on Customization.) You
can
edit that file by hand if you want to create an alias that will take
effect
immediately. However, the file will be deleted and recreated the next
time you
install ATK; permanent changes should be made in andrew/site/help.alias.
\subsection{1.2.1 Creating a help.alias file}
The file format for help.alias (and for the final installed help.aliases)
is
as follows:
\typewriter{\smaller{\indent{# comment
alias keyword
!comment
alias keyword
!comment
alias #command
!comment
}}}(The !comment part of each line is of course optional.)
Whenever a user asks for help on on any of the aliases, it will appear to
the
Help System as if the user had asked for help on the corresponding
keyword.
The standard help.alias file, for example, includes the following lines:
\typewriter{\smaller{\indent{password
type
cat
makefile
make
uncompact
compact
passwd
}}}If the keyword begins with the character '#', instead of behaving as
if the
user had asked for help on another keyword, Help will execute the command
after the '#'. This allows Help to show tutorials on various topics. An
example:
\typewriter{\indent{\smaller{emacs
#ez /usr/doc/emacs.manual
}}}
# commands will not be executed if help is run on a non-graphics system.
Using # commands is not encouraged, however, since users can open new
Help
windows using options on the \italic{Windows} menu card.
\section{1.3
Panel Contents
}
Configuring the Overviews and Programs panels in Help involves changing
the
following files:
\leftindent{\typewriter{/usr/andrew/lib/help.overviews}
\typewriter{/usr/andrew/lib/help.programs}}
These are installed by the Imakefile in andrew/helpindex.
The default versions of these files are in andrew/helpindex/help.ovrvw
and
andrew/helpindex/help.prgms. To install different versions, create new
files
called help.ovrvw and help.prgms and put them in the andrew/site
directory.
The next time you compile and install Andrew, your versions of these
files
will be installed instead of the default versions. If you just want to
install
the files without going through the whole build process, just copy them
to
lib/help.overviews and lib/help.programs in your destination tree.
(When Andrew is compiled at CMU (ie, if CMU_ENV is set), matters are
handled
differently. The site directory is not checked; the files
andrew/helpindex/cmucs.overvw and andrew/helpindex/cmucs.prgms are always
installed. Baroque, as we said.)
\subsection{1.3.1 Creating new Programs and Overview files}
Entries in both of these files are of the form:
\typewriter{\leftindent{panel item,keyword}}
"panel item" is the word or phrase you want to appear in the panel, and
"keyword" is the word you want Help to use when the user clicks on that
item.
So, for example, one entry you might have in
/usr/andrew/lib/help.overviews
is
\typewriter{\leftindent{Andrew Tour,tour}}
which puts the phrase "Andrew Tour" into the Overviews panel and uses the
word
"tour" as the keyword when a user clicks on "Andrew Tour." Be careful
not to
add extra spaces around the comma in the middle. (See the various
versions of
these files in andrew/helpindex for examples.)
\bold{To change the file retrieved by a panel item}, simply replace the
word
after the comma in a given entry with a different keyword. For example,
suppose you create your own help file about Andrew called andrew.help.
In
that case, you might want the panel item "Andrew Tour" to retrieve
andrew.help
instead of tour.help. You would modify the line in the help overviews
file
from
\typewriter{\leftindent{Andrew Tour,tour}}
to
\typewriter{\leftindent{Andrew Tour,andrew}}
Again, be careful not add extra spaces around the comma in the middle.
\bold{To add an item to the panels}, insert lines of the form shown above
into
the appropriate list of items. For example, suppose you want to add an
entry
in the Programs list for a program called "printtext" for which you have
created a help file.
You could add a new line of the form
\typewriter{printtext,printtext}
in the help programs file.
\bold{To remove an item from the panels}, delete or comment out (put a #
sign
at the beginning of the line) its entry in either help.overviews or
help.panels.
\section{1.4
Customization
}
\subsection{1.4.1 AndrewSetup Options
}
The configurations options that are most commonly changed on a site-tosite
basis can be specified in the AndrewSetup file, and thus changed
\italic{without} requiring the Help system to be recompiled and
reinstalled.
Those variables are described here. Note that when a variable's
description
refers to \typewriter{$ANDREWDIR}, it means that the option is preceded
by an
implicit "/usr/andrew" (or wherever the root of the Andrew software tree
is
for a particular system). Likewise \typewriter{$LOCALDIR }refers to the
local
software directory. Both \typewriter{ANDREWDIR} and
\typewriter{LOCALDIR} can
both be specified in the AndrewSetup file as well.
See help on AndrewSetup for the location of the AndrewSetup file and the
full
list of setup options available.
\leftindent{\bold{HelpIndex}: directory-name
Default value: $ANDREWDIR/lib/help.index
\indent{Indicates where Help should look for the default Help index
files.}
\bold{HelpLib}: directory-name
Default value: $ANDREWDIR/lib
\indent{Indicates where Help should look for the help.programs and
help.overview files to set up the Help system program and overview
panels.
}
\bold{HelpDir}: directory-name
Default value: $ANDREWDIR/help
\indent{Indicates where Help should look for help files to put into the
Help
system program and overview panels. (This is used if
$ANDREWDIR/lib/help.programs or $ANDREWDIR/lib/help.overviews is empty.)}
\bold{HelpChangeDir}: directory-name
Default value: $LOCALDIR/help
\indent{Indicates where Help can find "changes" files, indicating
revisions to
existing help files.}
\bold{HelpTutorialDir}: directory-name
Default value: $ANDREWDIR/help
\indent{Indicates where Help can find "tutorial" files, indicating
tutorials
on given help topics.}
\bold{HelpSendCommentAddress}: mailing-address
Default value: HelpComments+@andrew.cmu.edu
\indent{Indicates the address to which Help should send mail when "Send
Comment on Help" is selected from the menus.}}
\subsection{1.4.2 Compile-time Options
}
Further Help system customiztion is possible. Within the Help System
source
directory \typewriter{andrew/atk/help/src} is a file called
\typewriter{config.h}. This file contains all of the maintainercustomizable
options for help. Each line with an option is preceded by a small
description
of what that option is. Help can be further customized for a particular
site
by changing these options. The options referred to in this guide are
described below. Other options are explained in the
\typewriter{config.h}
file.
Note that merely changing this file is not sufficent to make the changes
made
go into effect. The help program must be recompiled and reinstalled for
the
changes to be visible.
The format of a variable is as follows:
\typewriter{/*
* Short description of the variable
*/
#define VARIABLENAME
}
\section{1.5
\italic{variable's default value}
Adding Help Files}
To develop a new help document for inclusion in /usr/andrew/help (or any
other
directory index by mkindex), take the following steps:
\leftindent{1. Use the "ez" editor to create a new file with a name of
the
form "filename.help". When you use EZ to create a new file with a
".help"
extension, EZ automatically loads the help template. Simply fill in the
template, adding or omitting sections as appropriate. The formatting
"styles"
used in the help template are
\leftindent{\italic{Chapter}: for the top line of the file
\italic{Section}: for major headings, headings at the far left
\italic{Leftindent}: around body text, to make the Section headings
distinct
\italic{Subsection}: for subheadings}
See the help file on EZ for information about how to add styles to a
document.
2. Copy the new file into /usr/andrew/help.
It should probably be
un-writeable so that people don't change the system file accidentally.
3.
Run "mkindex" to include the new file in the index for Help.
3. Try "help filename" after the new index is created to check whether
the
new help file is available. '
}Note that Help will able to find files installed into explicitly
searched
directories as soon as they have been installed, but that files added
into
directories that are only searched by \typewriter{mkindex} will not be
visible
until after \typewriter{mkindex} has been re-run.
\section{1.6
Updating Help Files}
To make changes to an existing file you do not need to re-run the index
once
the edited file is installed. Simply edit the file, either in place, or
edit
it in the source and install it.
\subsection{1.6.1 Where are the sources?
}
The sources for the Andrew help files are generally in the same directory
as
the piece of code that corresponds to the functionality described in the
help
file.
This means that finding help files can be quite difficult. When
your
sytem was constructed, the final step should have been to add lines to
/usr/andrew/help/help.aliases that serve both as aliases for shortened
filenames (see the next paragraph) and also as pointers to where some
files
came from. For example, to find the file about footnotes, you would do
the
following:
%\bold{ grep footnotes /usr/andrew/help/help.aliases}
ez-footnotes
fnote
!/afs/.andrew.cmu.edu/itc/vax_3/obj/andrew/atk/text
footnotes
fnote !/afs/.andrew.cmu.edu/itc/vax_3/obj/andrew/atk/text
These lines tell you that the source for the file is in andrew/atk/text,
prefixed by wherever your source is rooted.
\subsection{1.6.2 What are the files called?}
Many files are named the same name that appears in other help files as
keywords. The help file about EZ, for example, is called "ez.help."
However,
keywords in help files that are longer than seven characters, and/or have
a
hyphen in the keyword are mapped via the help.aliases file to files that
are
named differently. A good example is the footnote help file, above.
It
is
refered to in the ez.help file as "ez-footnotes", but the actual file
name is
fnote.help. The only way to find out the actual name of a file (like
fnote.help) is to "grep" the help.aliases file for the filename shown in
other
documents (like ez-footnotes).
\subsection{1.6.3 What is in the help files?}
In addition to information on a topic, be aware while you are editing a
help
file that italicized words are actually "links" between help files. In
other
words, one of the mechanisms by which users can navigate through Help is
by
using the \bold{Show Help on Selected Word} menu option, which depends on
words in the text being cued as keywords. While any selected text may be
used, keywords about which there are documents are often presented by
convention in the running text in italics, separated by two spaces for
easier
selection. For example, this is the way a word like \italic{printing}
is
signaled in running text as a keyword.
The references from one file to another form a loose "semantic network"
that
needs to be tended to if new files are added or old files are removed.
Unfortunately, there are no tools for maintenance beyond using "grep."
\section{ 1.7
Controlling the format of help documents}
All the documents included in /usr/andrew/help use a central template
that
controls their formatting. The help template is located in
\typewriter{\leftindent{/usr/andrew/lib/templates/help.template}}
The help template must be available or the help files will not display.
The use of a central help template is provided as a convenience for
maintainers of Help. If you wish to change some aspect of the formatting
of
help files, such as how the top line of help documents is displayed, you
need
only change the help template itself and all the help documents will be
changed accordingly.
See the help on \italic{templates} and
\italic{lookz}.
\section{1.8
Understanding the Help System
}
\subsection{1.8.1 Overview of Services and Features}
The Help program is designed to find and display information. Its most
common
use is as a documentation viewer though, with customization, it can be
used to
display any set of files on a system.
Help has ability to display many file formats, including ATK, troff, and
plain
text on both windowing systems and terminals, using the full capabilities
of
the display. On graphics displays, it can open multiple windows. Help
can
print any file that it displays.
Help runs with a system-level index that is created using a separate
program,
mkindex, which the maintainer uses to designate which directories are
searched
and thus which files are available through Help. In addition, Help also
has
the ability to search for files in user-specified directories in addition
to
the directories referred to by the index.
Help allows the maintainer to provide aliases for specific keywords.
If users request help on a keyword for which there is no file, Help can
keep a
record of the "missing" files, allowing the maintainer to improve the
system
by adding needed aliases and files.
There are many maintainer-configurable options, including keybindings,
help
file locations, help file ordering based on file extension, and panel
contents.
\subsection{1.8.2 Components of the Help system
}
\italic{User program:}
\leftindent{$(DESTDIR)/bin/help
source: andrew/atk/help/src}
\italic{Keyword mapping file:}
\leftindent{$(DESTDIR)/help/help.aliases
source: andrew/helpindex
}
\italic{Indexing program:}
\leftindent{$(DESTDIR)/etc/mkindex
source: andrew/helpindex}
\italic{Index input file}
\leftindent{See Indexing at CMU for location
source: andrew/helpindex/index.tpl}
\italic{Configuration files for the Overviews and Programs panels:}
\leftindent{$(DESTDIR)/lib/help.overviews
$(DESTDIR)/lib/help.programs
source: andrew/helpindex/help.ovrvw, help.prgms
}
\italic{Help template:}
\leftindent{$(DESTDIR)/lib/tpls/help.tpl
source: andrew/atk/text/tpls}
\italic{Man template:}
\leftindent{$(DESTDIR)/lib/tpls/man.tpl
source: andrew/atk/text/tpls}
\italic{Help file about Help:}
\leftindent{$(DESTDIR)/help/help.help}
\italic{Help maintainers guide:}
\leftindent{$(DESTDIR)/doc/help/Maint.doc}
\subsection{1.8.3 How Help works
}
Users invoke Help by typing
\typewriter{\smaller{\indent{help keyword}}}
at a shell prompt, where "keyword" is a topic about which they would like
information.
If no keyword is used with the "help" command, Help displays the file
associated with the keyword "tour." This default file (associated with
no
keyword or an unsuccessful initial keyword) can be changed and can be
different for the terminal version of help. (See the section on
Customization.)
\paragraph{1.8.3.1
What are keywords? }
Keywords are single words (no spaces) associated by default to the 'root'
of a
help file filename, namely the characters in the filename preceeding the
first
period. So, for example, "printers" is a keyword for a file called
"printers.help."
If there is more than one file that match a single keyword, Help presents
the
files in the following order:
\indent{1. Any file with the extension ".help", ".concept", or
".overview"
2.
Man pages, in numerical order
3.
FORTRAN man pages, in numerical order
4.
Any other file with the keyword as the root of the filename
}Note that any files that are found in a user-added explicit search
directory
will be shown in the above order \italic{before} any help files in the
indices.
This ordering is referred to as the \italic{file rotation}. The order in
which files are shown is based on file extension. This order can be
customized.
(See the section on Customization.) At Carnegie Mellon,
this
mechanism is used to create novice help files for standard commands like
'ls'
and 'rm' that will be shown to to user before the sometimes cryptic man
pages.
The default mapping of a keyword to a filename root can be overridden via
a
system level help.aliases file. (See the section below on Aliases.)
\paragraph{1.8.3.2
Where does Help find information?}
Help finds information about what files correspond to a given keyword by
looking in an \italic{index directory}. Help uses the index directory
\typewriter{/usr/andrew/help/help.index} by default. This directory can
be
changed. (See the section on Customization.)
Help cannot run without an index, but it can be made to use another index
instead of the default. Note that this is in place of the other index,
not in
addition to it. This can be used to use Help as an application-specific
help
system.
To specify an alternate index on the command line, the syntax is:
\typewriter{\indent{\smaller{help -i <index directory>}}}
Help can also be requested to search for files (without the aid of an
index)
in a given directory, in addition to the default help directories. This
is
done by using the \typewriter{-s} switch when invoking Help, or by using
the
help.searchpath preference. Note that since Help is not using an index
but
instead actually searching the directory itself, the keyword search will
be
slightly slower than an indexed search.
To specifiy another directory to search on the command line, the syntax
is:
\typewriter{\smaller{\indent{help -s <directory>}}}
If Help is going to be forced to search an additional directory on a
regular
basis it can be specified in a user's ~/preferences file using the
following
syntax:
\typewriter{\smaller{\indent{help.searchpath:<directory>:<directory>}}}
If a file in the directories specified by one of these two means has the
same
keyword as one or more files in Help's default directories, the order of
rotation is as follows:
\indent{1.
help -s directory
2.
help.searchpath directory
3.
Help index directories
}
\paragraph{1.8.3.3
What if Help doesn't find information?
}If Help does not find a file that is associated with the keyword
supplied by
the user, it informs the user that no help was found to match the keyword
and
creates a file in the 'Missing Directory',\typewriter{
/usr/andrew/help/HelpFlaws} by default, if the directory exists. If the
directory does not exists, or is unwritable, no action is taken. The
name of
this directory can be changed. (See the section on Customization.) The
file's name is \typewriter{Missing.keyword.n}, where \typewriter{keyword}
is
the topic on which the user requested help, and \typewriter{n} is a
number
corresponding to how many times that keyword has been requested as a help
topic.
At Carnegie-Mellon, this "Missing" information is collected and cleared
out on
a weekly basis and made into a message by BBD (~postman/bb-daemons/BBD)
that
is posted on andrew.daemons.help. In order for the Missing collection
and
posting mechanism to work, at least the following access list rights must
be
in place:
\typewriter{% fs la /usr/andy/help/HelpFlaws /usr/andrew/help/HelpFlaws
Access list for /usr/andy/help/HelpFlaws is
Normal rights:
system:anyuser rli
postman rlidwk
Access list for /usr/andrew/help/HelpFlaws is
Normal rights:
system:anyuser rli
postman rlidwk}
Also, the directory /usr/andrew/help/HelpFlaws needs to be a separate
read-write volume, because /usr/andrew/help is a read-only replicated
volume.
\paragraph{1.8.3.4
How does Help display the information?} In order
for help
to be able to correctly display different file formats, all help files
must
follow standards for their particular type. Namely, all troff files must
have
'.' or '#' as their first character, and all ATK files must be valid ATK
datastreams. Any file not following these standards will be treated as
an
unformatted text file.\bold{
}From within a window manager:
\indent{If Help is invoked from within a window manager, and there is not
another Help window already running, a new Help window opens.
Help can
be
forced to open a new window if there is one already open with the
\typewriter{-new }command-line switch, like so:
\smaller{\indent{\typewriter{help -new keyword}}}
Help will then display the first file in the rotation, if any were found.
If
no files were found, Help will put up a error message, and will then
display
help on the default keyword as mentioned previously This default keyword
can
be changed, and may be specified based on whether Help is running on a
terminal or under a window manager. (See the section on Customization.)}
Outside a window manager:
\indent{If Help is invoked from a terminal or a terminal-emulator, (i.e.,
any
device that does not support graphics) Help will use \typewriter{nroff}
to
display help files using whatever capabilities the terminal supports.
ATK
help files are first converted to nroff before being displayed. The file
is
displayed using \typewriter{more} to allow the user to page through the
file
one screenfull at a time. If the user has set the environment variable
\typewriter{PAGER}, help will use the value of \typewriter{PAGER} as the
paging program instead of \typewriter{more}. The default pager, and the
path
necessary to run \typewriter{nroff} can be changed. (See the section on
Customization.})
\begindata{bp,17342524}
\enddata{bp,17342524}
\view{bpv,17342524,0,0,0}
Copyright 1992 Carnegie Mellon University and IBM.
\smaller{\smaller{$Disclaimer:
All rights reserved.
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,17298436}