8.2 Browse: Accessing The Files Through The Polaris Help System

Accessing the Files Through the Polaris Help System
titles will appear on the user’s screen.
If the search fails, the system will prompt the user for a full-text search:
•Full-text searches compare the user’s string to all text within all help files.
•If this search is successful, and returns a single document, the file will appear on
the user’s screen.
•If the search is successful, and returns more than one document, a list of the docu-
ment titles will appear on the user’s screen.
8.2 Browse
A user can browse the system simply by clicking on purple or underlined text. Purple or
underlined text indicates hypertext links. Clicking on the text will bring up more
detailed information on that text.
The Polaris Help System: Care and Feeding 14 of 14

•To have a certain document for all system types, but to ALSO have a Macintosh-
specific version, accessible only to Macintoshes, name the general document,
“hardware.help” and name the Macintosh document, “hardware.help.mac_os”.
•To create struct files that are system-specific, name the document,
“info.help.struct.sun4_413”.
Polaris supports five system-specific filename tags:

•sun4_413
•pmax_ul4
•hp700_ux90
•pc_win
•mac_os
When you run the “make” command, the files will be established for the proper system
types.
7.6 Aliases
Aliases can be very damaging to the system; they can damage the search functionality.
For example, if you establish an alias called “help” for the document titled “advisor,”
you are essentially telling the system that the key word “help” is identical to the key
word, “advisor;” if the user were searching for help on the Andrew system, he would be
denied that information.
Computing Services keeps track of failed searches; if it is found that certain aliases are
appropriate, they can be added at a later date.
8.0 Accessing the Files Through the Polaris Help

System
8.1 Searches
A user enters a string of text. Polaris compares this string to
(a) file names
(b) HTML title fields
(c) HTML H1 headers
If the search is successful, and returns a single document, the file will appear on the
user’s screen.
If the search is successful, and returns more than one document, a list of the document

Adding Documents to the Polaris Help System
To set the mode, use:

•chmod 544 <filename>
or
•chmod u + x <filename>
Each help document must have a corresponding doc/browse file. For example, the
guidelines.help file has a corresponding doc/browse/guidelines file. It looks like:
<html>
<head><title> System Usage Guidelines</title></head>
<body>
<h1> System Usage Guidelines</h1>
</body>
</html>
7.4 Formatting1
When formatting HTML documents, please try to:
•Use the <html> and </html> flags at the beginning and end of your text.
•Use the <head> and </head> flags to indicate the document heading.
•Use the <body> and </body> flags to indicate the body of the document.
•Beware of nesting flags inside of other flags! For instance, the text inside of
<head> flags should never be in the <body> flags as well.
7.5 System-Specific Documents

Certain documents may only be intended for certain system types.
•To have a document accessible by all system types, name the document, “soft-
ware.help.”
•To have the document only be accessible to PCs, name the document
“software.help.pc_win.” (Please note that if you do name a document “soft-
ware.help.pc_win, be sure to name the struct file “software.help.struct.pc_win.
1. For further information on HTML flags and formatting suggestions, see “A Beginner’s Guide
to HTML”
(http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html).

This title is from the H1 heading in the doc/browse/guidelines file:
<h1> System Usage Guidelines </h1>
This is the trailer found in the helpdoc/headers+trailers directory. The Polaris system
automatically appends this trailer. If you don’t want this trailer added to your document,
set it’s mode to 544.

Because “TopPage” is listed in the struct file, a hyperlinked reference to “System Usage
Guidelines” appears on TopPage.

•the document itself

•a corresponding doc/browse file
You can also add:

•struct files
•aliases
7.1 The Document

Currently, all the help documents are either in ATK or HTML.
•ATK files must go into the doc/help directory.
•HTML files must go into the doc/html directory.
All help files should be tagged with the.help flag. For example, if your subject is “ez,”
title the document “ez.help”
7.2 The struct Files

Struct files create references to your document within other files. It is not required to
create struct files for all documents in the system, but it is highly recommended because
these files add functionality and creating these references is quite simple.
7.3 An Example
You want to create a help document that lists system usage guidelines. You would like a
reference to this document in the Top Page of the Help System because you think that
system usage guidelines is an important topic.
Since your doc/browse file is named “guidelines” name your struct file “guidlines.help”
and place it into the struct/browse directory.
The struct/browse/guidelines.struct file looks like this:

TopPage
<a href= “guidelines”> System Usage Guidelines</a>

6.1.3 The alias Directory

The alias directory contains a single file titled ‘helpdoc.’ This file contains a copy of the
aliases currently established by the system. The file listings include:
datacommunication: datacomm;
datacommunications: datacomm;
advise: consulting;
telecommunications: telecomm;
a.out: programming;
For example, if a user were to type “advise” when searching the Help System, the sys-
tem would run a search to bring up the file titled ‘consulting.’
6.1.4 The doc Directory

The doc directory contains four subdirectories:
browse
contains a document’s title and <h1> heading.
html
contains HTML-formatted help documents.
headers+trailers
contains the standardized search trailer; as a default, this trailer always comes at the
end of every document.
help
contains the ATK-formatted help documents.
6.1.5 The struct Directory

The struct directory also contains the following subdirectories:
browse
contains the struct files for the corresponding doc/browse files.
html
contains the struct files for the corresponding doc/HTML files.
help
contains the struct files for the corresponding doc/help files.
7.0 Adding Documents to the Polaris Help System
When you add documents to the system, you must add:

The Files and Directories of the Polaris System
6.0 The Files and Directories of the Polaris System
/afs/andrew/system/src/local/helpdoc/009
Makefile
README.andrew Makefile.sys
GNUmakefile alias
helpdoc struct
doc
html
headers+trailers html help
browse
browse help
6.1 The Directory Structure

Within the /afs/andrew.cmu.edu/system/src/local/helpdoc directory are versions of the
Help Document.
TABLE 5. The Polaris Help System
Directories Files
alias GNUmakefile
doc Makefile
struct Makefile.sys
README.andrew
6.1.1 The Makefile files

The Makefiles contain the rules which are employed to propagate files from the source
area to system-specific destinations.
6.1.2 The README file

After changes have been made to the source area, the README file tells you how to
simply type in the command, “make” to begin the “make” process.

AFS Side
The files themselves come from several places, as indicated by the following table.
TABLE 4. Polaris File Areas
Area Use
wsadmin/services/specific/polaris Many misc. files, including the prefetch configuration,
the proto polaris index, the depot configuration, and
the depot prototype files for the various env/sys/tree
areas.
wsadmin/services/lib Misc config files that don’t wind up under /usr/polaris
(for example, /etc/fultext, /etc/rc.local.polaris, and the
crontab file)
host/ful-cgi The CGI used at runtime to access polaris
host/www-srvr The www server
host/help System and environment independant files used in
building the system and at runtime (for example,
Trailer and DefaultBrowsePage)
host/helpwrap Programs used to build the system (for example,
polaris, man2html, atk2html, and other support pro-
grams).
host/fulcrum The fulcrum libraries and programs (for example, ftin-
dex)

AFS Side
flow.” This can happen if some element that’s inserted into the catalog is too long (title
is a good one at causing this when htmlwrap doesn’t parse the file correctly)
To reindex polaris, run:
ftindex -v -r polaris
If a collection is locked, run:

ftlock -u polaris
to unlock it.
In some rare cases, you may want to delete the collection and build it again from
scratch. To delete the collection, use:
ftremove polaris
and to recreate the collection, use:
unsetenv HOME
ftcreate polaris
Normal polaris runs are only incremental updates. If the data is corrupted, however, you
may wish to do a full update. To accomplish this, create the file /usr/polaris/etc/FullUp-
date. The existence of this file will cause the master script to run the commands with
arguments telling them to recreate everything from scratch. Note that this can take a
considerable about of time.
5.0 AFS Side

To make a machine a Polaris server, add “%define doespolaris” to the package.proto
file. Any machine with this definition will pull down the files needed to be a polaris
server.
TABLE 3. Polaris Package Files
File Effect
polaris.generica Specifies where most of the polaris files come from

polaris.env.generic Sets up each polaris environment
polaris.sys.generic Sets up each polaris system
polaris.tree.generic Sets up each polaris tree
a. Polaris package files are in the wsadmin/services/lib area

Failure Cases
minal), /usr/polaris/bin/nroff2html (which converts the terminal escapes to html), /usr/

polaris/bin/htmlwrap (which creates links to other man pages, and inserts a <title> ele-
ment), and htmlclean.
3.2.3 Htmlclean
/usr/polaris/bin/htmlclean is the common final filter that all the pages pass through. It’s
responsible for resolving the following special markers:
•&sys; Translates into the current system type.
•&env; Translates into the current environment type.
•&event; Translates into /extra/<current environment>/<current systype>/ current
tree/. If you want to have a URL to an image, put the image in lib/polaris/extra/
<collection name>, and in the URL put &extra; <collection name>/ <image>.
•&sysname; Translates into the current system name.
•&envname; Translates into the current environment name.
3.2.4 Browsebuilder
After depot runs, /usr/polaris/bin/browsebuilder is invoked to rebuild the pages in the
area’s browsegen directory. It starts by slurping in the default browse page1, all of the
base pages in the browse directory, and all of the struct files in the struct directory. It
then uses this information to regenerate the entire contents of the browsegen directory.
3.3 Prefetch
/usr/polaris/bin/prefetch runs the queries in /usr/polaris/etc/prefetch.conf, caches the
results in /usr/polaris/prefetch, and builds the NDBM files /usr/polaris/etc/
prefetch.{dir,pag}, which the server later uses to look up the queries.
4.0 Failure Cases
4.1 When Depot Fails

If depot fails in an area, the log file should contain enough information to help you fig-
ure out what’s going on.Running depot by hand is not advised, unless you set all of the
environment variables set by /usr/polaris/bin/polaris yourself.
4.2 When the Indexer Fails

Examine the log file, /usr/polaris/fultext/polaris.log. This will list the files as it indexed
them, as well as a more detailed error message. The last file in the list is probably the
cause of the error message. Most of the time, errors come from a “catalog record over-
2. Many vendors shorten man page names as far as possible, “to be conformant to all filesystem
conventions.” This can annoy users who search for XmToggleButtonGadgetGetState, and fail,
when searching for XmToggleBuE would get the desired document, and XmToggleBut would
give a list of possibilities.
1. /usr/polaris/html/DefaultBrowsePage

Parts of Polaris
TABLE 2. Interesting Polaris Variables
Variable Effect
@envnames The names of the environments, as used to replace
&envname; in HTML documents
@sysnames Same as @envnames visavis &sysname;.
@trees The list of trees
$opt_n The maximum level of parallelization; i.e. the maxi-
mum number of depot areas that may be processing
simultaneously.
Because the master script may be run both by reboot and by cron, it uses semaphore 80
as a lock. It also allocates a private semaphore to limit the number of areas simulta-
neously updating.
When the master script runs, it forks off a process for each environment/system/tree
combination. When a process gets a hold on the semaphore, it runs dpp, depot, and
browsebuilder to update its area.
When all the areas have been updated, the master script builds a new thesaurus file by
catting together /usr/polaris/fultext/polaris.fts and all of the alias files in one of the areas
(specified in the script) and running fthmake to produce /usr/polaris/fultext/polaris.fth.
It then runs ftcin over /usr/polaris/fultext/polaris.init to make sure that all of the directo-
ries are in the thesaurus (indexing removes empty directories), and runs ftindex to
rebuild the index files in /usr/polaris/fultext. The ftindex log is /usr/polaris/fultext/
polaris.log; this can be very useful when diagnosing indexer failures.
/usr/polaris/bin/prefetch is run, to prefetch certain costly queries.
A summary is mailed to acs+asg.log.polaris.
3.2 Depot
Depot is responsible for turning all of the help documentation into HTML. Currently, it
applies atk2html to files in the help directory, man2html to files in the man directory,
htmlclean to the files in the html directory. To add additional filters to the Polaris sys-
tem, the new filters must be added into the depot.generic file found in: wsadmin/ser-
vices/specific/polaris/etc/depot.generic.
Depot also copies down the contents of the struct, browse, and alias directories, and
removes all others.
3.2.1 Atk2html
/usr/polaris/bin/atk2html reads the ATK BE2 datastream format, converts it into HTML,
and filters the result through htmlclean.
3.2.2 Man2html
/usr/polaris/bin/man2html is a complicated little process that determines whether or no
the source man page is compressed1, figures out the real name of the file2, sends the
page through groff (which turns it into something that would look reasonable on a ter-
1. As in the case with HPUX

Parts of Polaris
when polaris should be updated.
TABLE 1. Contents of /usr/polaris
bin etc fultext html

atk2html depot.conf fultext.ftc DefaultBrowsePage
browsebuilder depot.generic polaris.cat DownMessage
ftcin httpd.conf polaris.cfg FallbackPostfix
ftcout prefetch.conf polaris.cix FallbackPrefix
ftcreate prefetch.dir polaris.dct SearchNoHits
fthmake prefetch.pag polaris.fth SearchYesHits
ftindex robots.txt polaris.fts Trailer
ftiprt tmac.html polaris.init polaris
ftlock polaris.log
htmlclean polaris.ref
htmlwrap polaris.stp
logger
man2html
nph-help
nroff2html
polaris
prefetch
3.0 Parts of Polaris
3.1 Polaris
/usr/polaris/bin/polaris is the master polaris build script. It’s run by /etc/rc.local.polaris
on reboot, and nightly via cron. It’s responsible for running dpp, depot, and browse-
builder in all of the documentation areas, and running the programs to update the the-
saurus and index.
Most of the configuration for the script is located at the top of the script, where a num-
ber of variables are assigned.
TABLE 2. Interesting Polaris Variables
Variable Effect
@environs The list of environments
@systems The list of systems

June 7, 1995
The Polaris Help System:

Care and Feeding
1.0 Introduction
The Polaris Help System is Carnegie Mellon University’s integrated computer help sys-
tem project. It provides on-line help on the following CMU-supported platforms:
Unix: Sun Microsystems (SunOS 4.1.3)

Unix: Hewlett Packard (HPUX 9.0.3)
Unix: DECstation (Ultrix 4.2a)
PC (Microsoft Windows 3.1/DOS 6.2)
Macintosh (System 7.0.1)
Polaris runs on all the supported systems, providing information appropriate to the beta
and gamma environments. Polaris consists of help files and a set of maintenance pro-
grams. It is released throughout the campus network using depot. When a user types
help, a viewer (Mosaic/Netscape/Lynx) is invoked, displaying the top level screen. The
user can navigate through the help system as desired by browsing through linked files or
by searching for a specific term.
2.0 Polaris Directory Structure

On the polaris server, most of the configuration is located under /usr/polaris; exceptions
to this rule include /etc/rc.local.polaris, /etc/fultext, and the crontab file which specifies
1 of 14

8.2 Browse: Accessing The Files Through The Polaris Help System

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

8.2 Browse: Accessing The Files Through The Polaris Help System

Hochgeladen von

Copyright:

Verfügbare Formate

Accessing the Files Through the Polaris Help System

titles will appear on the user’s screen.

The Polaris Help System: Care and Feeding 14 of 14

Polaris supports five system-specific filename tags:

8.0 Accessing the Files Through the Polaris Help

The Polaris Help System: Care and Feeding 13 of 14

To set the mode, use:

<head><title> System Usage Guidelines</title></head>

<h1> System Usage Guidelines</h1>

7.5 System-Specific Documents

The Polaris Help System: Care and Feeding 12 of 14

This title is from the H1 heading in the doc/browse/guidelines file:

<h1> System Usage Guidelines </h1>

The Polaris Help System: Care and Feeding 11 of 14

The Polaris Help System: Care and Feeding 10 of 14

•the document itself

You can also add:

7.1 The Document

7.2 The struct Files

The struct/browse/guidelines.struct file looks like this:

<a href= “guidelines”> System Usage Guidelines</a>

The Polaris Help System: Care and Feeding 9 of 14

6.1.3 The alias Directory

6.1.4 The doc Directory

6.1.5 The struct Directory

7.0 Adding Documents to the Polaris Help System

When you add documents to the system, you must add:

The Polaris Help System: Care and Feeding 8 of 14

6.0 The Files and Directories of the Polaris System

6.1 The Directory Structure

TABLE 5. The Polaris Help System

6.1.1 The Makefile files

6.1.2 The README file

The Polaris Help System: Care and Feeding 7 of 14

TABLE 4. Polaris File Areas

The Polaris Help System: Care and Feeding 6 of 14

If a collection is locked, run:

5.0 AFS Side

TABLE 3. Polaris Package Files

polaris.generica Specifies where most of the polaris files come from

The Polaris Help System: Care and Feeding 5 of 14

minal), /usr/polaris/bin/nroff2html (which converts the terminal escapes to html), /usr/

4.0 Failure Cases

4.1 When Depot Fails

4.2 When the Indexer Fails

The Polaris Help System: Care and Feeding 4 of 14

TABLE 2. Interesting Polaris Variables

1. As in the case with HPUX

The Polaris Help System: Care and Feeding 3 of 14

when polaris should be updated.

TABLE 1. Contents of /usr/polaris

bin etc fultext html

3.0 Parts of Polaris

TABLE 2. Interesting Polaris Variables

The Polaris Help System: Care and Feeding 2 of 14

The Polaris Help System:

Unix: Sun Microsystems (SunOS 4.1.3)

2.0 Polaris Directory Structure

Das könnte Ihnen auch gefallen