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.
To add documentation or adjust documentation
.doc files should live in ~g/doc. In full, that is
/afs/cs.cmu.edu/project/learn/group/doc
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.