CONTENTS
To add documentation or adjust documentation
----- Obvious but important:
The doc2html.pl program
----- Annotations in a .doc file.
The contents of this line are a biggy type heading
----- The contents of this line are a littly type heading
This line begins with $h
----- This line begins with $s
Many of these pages (including this one) are created with doc2html, an ultra simple way to turn plain text into non-horrible HTML. See below for an explanation.
Some of them (e.g. the EYE documentation) were created by latex2html.
And the "overview" page is just a regular html page.
To add documentation or adjust documentation
Choose which of the three: .doc , .tex or .html, you are going to work with. If you're adjusting someone else's documentation you have no choice.
.doc files should live in ~g/doc. In full, that is
/afs/cs.cmu.edu/project/learn/group/doc
If you have a latex documentation called xx.tex, make a subdirectory called g/doc/xx . Latex xx.tex in that subdirectory. Then run latex2html xx.tex. The link to the resulting html file will be xx/xx/xx.html relative to the g/doc directory.
If you're adjusting documentation created with latex, don't alter the .html file directly. Alter the .tex file then run latex2html.
If you're adjusting documentation created with doc2html, don't alter the .html file directly. Alter the .doc file then run doc2html.
The source files for these documents are in
/afs/cs.cmu.edu/project/learn/group/doc/*.doc
The source files are almost entirely plain ASCII text, so they are pretty easy to string together from old email, code fragments etc. See below about the few embellishments beyond simple ASCII. So to create a new documentation page do:
(1) Create the source documentation file plop.doc
(2) Then run: gmake
This will automatically produce both an html file and a formatted ASCII text file from plop.doc, using the commands:
doc2html.pl plop.doc >! plop.html
lynx -dump plop.html >! plop.text
(3) Update overview.html in the same directory to include a link to plop.html
The very first line of the file will be used as the html title, and the written title of the html page.
A blank line is interpreted as a paragraph break.
All other text is interpreted as plain text unless the line begins with one of the following strings.
$h The contents of this line are a biggy type heading
$s The contents of this line are a littly type heading
$v The contents of this line should be displayed
verbatim in fix-width font, indented somewhat.
Heading lines will also automatically be incorporated into a hyperlinked table of contents at the top of your document.
Examples:
This line begins with no special annotation.
This line begins with no special annotation.
This line begins with $v
This line begins with no special annotation.
This line begins with no special annotation.