The Polaris Help System:
Care and Feeding
CONTENTS
Introduction
Polaris Directory Structure
Parts of Polaris
Failure Cases
AFS side
The Files and Directories of the Polaris System
Adding Documents to the Polaris System
Accessing the Files Through the Polaris Help System
1.0: Introduction
The Polaris Help System is Carnegie Mellon University's integrated computer help system project. It provides on-line help on the following CMU-supported platforms:
- Unix: Solaris 2.5.1 (Sun Microsystems)
- Unix: HPUX 9.0.3 (Hewlett Packard)
- Unix: Ultrix4.2a (DECstation)
- Microsoft Windows 3.1/DOS 6.2 (PC)
- MacOS 7.0.1 (Macintosh)
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 programs. It is released throughout the campus network using Depot. When a user types "help", a browser (Mosaic/Netscape/Lynx) is invoked, displaying the top level Polaris 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 when Polaris should be updated.
TABLE 1: Contents of /usr/polaris
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 browsebuilder in all of the documentation areas, and running the programs to update the thesaurus and index. Most of the configuration for the script is located at the top of the script, where a number of variables are assigned.
TABLE 2: Interesting Polaris Variables
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 simultaneously 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 directories 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 new filters to the Polaris system, the new filters need to be added to the depot.conf file in /wsadmin/services/specific/polaris/etc. It 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 not the source man page is compressed, figures out the real name of the file, sends the page through groff (which turns it into something that would look reasonable on a terminal), /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> element), 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 the following special markers:
&sys; Translates to the current system type.
&env; Translates to the current environment type.
&extra; Translates to extra/ current environment / current systype / current tree /. If you want to have a URL to an image, put in the URL, &extra; collection_name/ image_name, and put the image in lib/polaris/extra/ collection_name.
&sysname Translates to the current system name.
&envname Translates to the current environment name.
3.3: 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 page, 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.4: 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 figure 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 give you 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 overflow." 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:
If a collection is locked, run:
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:
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/FullUpdate. 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 amount 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
The files themselves come from several places, as indicated by the following table.
TABLE 4: Polaris File Areas
6.0: The Files and Directories of the Polaris System
7.0: Adding Documents to the Polaris Help System
When you add documents to the system, you must add:
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>
Because "TopPage" is listed in the struct file, a hyperlinked reference to "System Usage Guidelines" appears on TopPage.
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 doc/headers+trailers directory.
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: Formatting
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, "software.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 "software.help.pc_win," be sure to name the struct file "software.help.struct.pc_win.")
- 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 hurt 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 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 titles will appear on the user's screen.
If the search fails, the system will prompt the user for a full-text search:
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.
Return to: Polaris Home Page | Andrew II Home Page
