\begindata{text,539411208}
\textdsversion{12}
\template{default}
\define{global
}
\define{footnote
attr:[Flags OverBar Int Set]
attr:[FontSize PreviousFontSize Point -2]}
\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]}
\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-directory-name 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.
-v
specifies "verbose" mode.
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,539464600}
\textdsversion{12}
Or possibly just broke.\
\enddata{fnote,539464600}
\view{fnotev,539464600,0,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.
input
files reference directories like
So, different index
/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
into the
an entry
you have
add an item to the panels}, insert lines of the form shown above
appropriate list of items. For example, suppose you want to add
in the Programs list for a program called "printtext" for which
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: info-andrew-request+help@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
maintainer-customizable 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 applicationspecific
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/bbdaemons/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,539485400}
Version 2
n 0
\enddata{bp,539485400}
\view{bpv,539485400,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 and without fee is hereby granted,
provided
# that the above copyright notice appear in all copies and that both that
# copyright notice and this permission notice appear in supporting
# documentation, and that the name of IBM not be used in advertising or
# publicity pertaining to distribution of the software without specific,
# written prior permission.
#
# THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD
# TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ANY 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,539411208}