Alpha_1 Meta-documentation

This page documents Alpha_1's on-line, html-based documentation. All Alpha_1 web pages should adhere to the guidelines specified here.

Available Documentation

There are three branches of the Alpha_1 documentation, readable by the following groups: Access to these pages is granted based on each individual's association with the project. The home page is accessible to the world, our users also have access to the User's Manual, and our developers can access all three. These pages have been designed so that each user has a single point of entry into the Alpha_1 documentation.

Web Documentation Guidelines

The Alpha_1 User's Home Page and the Alpha_1 Developer's Home Page are roots to large heirarchies of pages. In order to make navigation easier, the major branches of these manuals, have a standard title and an associated image which is at the top of each page. All pages that fall under a given heading have the same title and image. At the bottom of most pages is a small logo which is a hyperlink to the top of the current manual branch. When at the top of a branch, the logo is linked to the next level up in the manual hierarchy.

New Documentation

Modifications to existing documentation pages should be made by checking out the appropriate pages via CVS, modifying them and checking them back in.

To add a new page to an existing manual execute the following steps in your working directory:

  1. copy the source for the appropriate sample html page (see below) to the appropriate manual directory,
  2. add the body text to the new page,
  3. change the standard image and button references to relative paths,
  4. use cvs add to add the new file to the CVS repository, and
  5. check in the file.
To create an entirely new sub-branch of the documentation...

HTML Tools

The HTML Tools page contains information on converting latex documents (including equations) to HTML, how to capture images, and how to make gifs transparent.

Sample Pages

Sample pages for each of the manuals and their main sub-branches are provided. They should be used as a starting point whenever adding a new page to one of these manuals.

Table of Contents

If an HTML document is more than about two screens long, or if it has a large number of sub-sections, it should have a "Table of Contents" at the top of the page. Each entry in this table should link to the appropriate section of the document. For an example, see the C_Shape_Edit Developer's Guide.

Standard Images

As mentioned above, each manual and some sub-manuals have a standard image at the top of each page. In some cases, a smaller version of that image is used as the "Return" button at the bottom of the page. In order to facilitate updating these images in the future, each image has a standard file name such as users-image.gif and users-image-button.gif. Overwriting one of these files with a new image changes the image used on every page in the effected manual. Each of the standard images and button images can be seen on the sample web pages mentioned above.

All standard images for the Developer's Manual and its sub-manuals should be stored in /home/alpha1/src/a1src/sman/images. All standard images for the User's Manual and its sub-manuals should be stored in /home/alpha1/src/a1src/man/images.

Alpha_1 Developer's Manual Home Page
Alpha_1 Developer's Manual. Version 95.06.
Copyright © 1995, University of Utah
alpha1@gr.cs.utah.edu