Writing documentation for Medusa

Overview

The documentation is based on the principle of least extra work. That is, UWM people should be able to add documents simply by adding files, and those files should be straight HTML content with as little as possible style or navigation information.

Style and navigation information are provided by Mason; more specifically, by the autohandler, toc, and style files in the medusa root directory. These are available under CVS, but under normal circumstances no one but the webmaster should modify them.

Mason produces the header, footer, and navigation bar (at left). The header and footer are pretty standard, but the navigation bar comes from reading the actual directories and filenames (see below).

CVS

The only way to modify what shows on the web page is through cvs commit. This will automatically run cvs update on the web pages. If you are writing straight HTML without any Perl or Mason, you can preview your changes on your machine using an URL such as file://path/filename.html (without the header, footer, and bar).

First you need to check out your own copy:

cvs -d :pserver:user@gravity.phys.uwm.edu:/usr/local/cvs/medusa login
cvs -d :pserver:user@gravity.phys.uwm.edu:/usr/local/cvs/medusa checkout web
cvs -d :pserver:user@gravity.phys.uwm.edu:/usr/local/cvs/medusa logout

So you want to add a file

First, the filename. The title of the document and the phrase referring to it in the navigation bar at left are determined by the filename. Both are simply the filename, without the extension, with underscores turned to spaces, and the first letter of each word capitalized. (Any exceptions, like all-caps for abbreviations, are hard-coded into the autohandler. Ask the webmaster if you want to add one.) Which directory you put the file in determines which heading it sits under in the navigation bar.

Now that you've got a filename, start editing the file. Please do this by hand. It's not hard, and things like Netscape Composer routinely produce bad HTML. Mason expects your document to be proper HTML, and in at least one case (% at the beginning of a line) has barfed on Composer output.

As far as writing the HTML goes, just dive in and start writing content. No header info, colors, etc. are necessary. Mason handles that.

Please don't micromanage things like <font color=green>. If you want to indicate keyboard input, for instance, write <kbd>command</kbd>. A side effect of good HTML is that cascading style sheets work. If you use a general command like <h1> or <kbd>, the style file will automatically give it a font, color, etc. consistent with the other pages. We have had problems with people using different color schemes, having trouble telling commands from hyperlinks, etc.

End your file with the following lines:

<p>
<hr>
<address>
$Id: documentation.html,v 1.11 2003/05/23 19:24:53 duncan Exp $
</address>

Do not forget to use cvs add -kb filename if you are adding a file that is not plain text, e.g. postscript files, JPEGs, etc. If you forget to do this, CVS may corrupt the files. To correct an already committed file, see the GNU info page for cvs in the "Binary Files" section under "CVS and the Real World"

After the page has been committed, use the links at the bottom of the public version to check for dead links and HTML or style problems. But these links are not infallible, thanks to various browsers' different quirks. You should still follow good coding practice: indent the tricky bits, keep the lines under 80 characters, etc. Regarding line length, use the "strip it for printing" link at the bottom of your committed page to check if something is making it too wide for printing and fix it if it is.

Adding questions to the FAQ

The medusa FAQ at http://www.lsc-group.phys.uwm.edu/cgi-bin/faqprocessor.cgi generates the questions and answers from the contents of the plain text file faq.txt that is at the top level of the medusa web page CVS. To add or change questions, edit the file fax.txt and then check the changes into CVS.

The format of this file is pretty simple:
Questions should start on a new line with Q: and be followed by the answer starting on a new line with A:
New sub headdings can be added by a line starting with SUBHEAD:
For example, to add an "FAQ" section to the FAQ, one would add the following text:

SUBHEAD: About this FAQ

Q: Where is the program that generates this FAQ?
A: The HTML is generated by a CGI script that is located on gravity at
<tt>/var/www/cgi-bin/faqprocessor.cgi</tt>

Q: How do I add questions to this FAQ?
A: Read the 
<a href="http://www.lsc-group.phys.uwm.edu/beowulf/medusa/maintenance/documentation.html">
documentation instructions</a> on the medusa web pages.

You can use standard HTML in the questions and answers for formatting, links, etc.