OUTLINE

	Create linked group of HTML files from simple
	plain text files.
	
	Structure is indicated with indentation.
	
	Links are implicit--writing the name of a file
	always creates a link to the file.  Similarly, writing
	the name of an image always inserts the image as
	an inline image.  Textual markup is similar to that
	commonly used for Usenet news, e.g. _italic_
	and *bold* text.

USAGE

	outline inputfile [templatefile] > output.html
	
	If 'templatefile' is given, it should be a template
	HTML file, except containing '%(title)s' where the
	title generated from 'inputfile' should go, and
	'%(body)s' where the rendered HTML version of
	'inputfile' should go.
	
	A sample templatefile would be:
	
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
	<HTML><HEAD><TITLE>%(title)s</TITLE></HEAD>
	<BODY>
	%(body)s
	</BODY>
	</HTML>

PARSING STAGES

	There are three stages of parsing a file: outline, paragraph, character.

Outline Stage:

	The document is broken into a hierarchy of "chunks",
	based on indentation.  
	
	Each new chunk is made a child of the most recent
	chunk with indentation less than the new chunk's.
	Each 'tab' is considered to be equivalent to 8 spaces
	for the purposes of comparing indentation.
	
	A warning is generated if two children of the same
	chunk have different indentations.
	
	Each new non-empty line is taken to be a new "chunk",
	except:

		(by _last_ character, we mean last non-white-space
		character).
		
		If the _last_ character in a line
		is an unescaped '\', the logical line is considered to
		be continued by the next physical line.

		If the _first_ character in a line
		is a '[', the logical line is considered to continue until
		an unescaped ']' is the _last_ character on a line.
	
	Chunks starting with '#' are comments
	
	Chunks starting with ?string are conditional, and
	included if and only if 'string' is defined when rendering.
	This is to allow some text to be included only in the
	printable or the teachers' version.
	
	The outline markup marks will be removed before
	passing the text on to the Paragraph stage.

Paragraph Stage:

	The first paragraph will be used as the title and
	first H1.  Subsequent left-aligned paragraphs
	are H2s.  All indented paras are inside
	nested ULs.

	The paragraph may be treated specially depending
	on the first character.  The characters |, = and <
	are special.
	
	Paras beginning with | are treated
	as example code, i.e. they are not processed except
	to quote characters that would be otherwise interpreted
	as HTML code.
	
	[Paras beginning with '=' are treated as HTML code.
	They are not processed at all, i.e. are passed through
	as-is.]
	
	[Paras beginning with '<' may have an optional '|' or '='
	sign directly afterward, then a filename.  The named
	file will be included, and then processed normally,
	as an example or as pure HTML.  A warning will be 
	delivered if what follows the '<' isn't exactly what
	we expect, or if the file referenced can't be read.]
	
	| example paragraph
	= HTML paragraph
	< file	# include file
	<| file	# include file as an example
	<= file	# include file as HTML

Character Stage

	This stage is responsible for character-level markup
	and linking to other files and images.
	
	For the purposes of our discussion, a paragraph is
	broken up into "words" separated by whitespace,
	that is any punctuation is considered part of the word.
	
	Character markup is indicated with special characters
	that appear at the beginnings or endings of words.
	Character markup can nest, but cannot overlap.
	Start symbols must appear at the start of words,
	end symbols must appear at the end of words,
	and pairs must match up, or a warning is generated,
	and NO character markup is applied to that paragraph.
	
	The character styles which currently can be used are:
		$constant-width$
		_italic_
		*bold*
		^superscript^
	
	Everything which can be turned into a link _is_ turned
	into a link.
	
	Words are tested _first_ to see if they may be links,
	and then afterwards for character styles.
	
	Obvious URLs like 'http://non-whitespace' and
	'mailto:non-whitespace' are turned into links
	and displayed with constant-width font.
	
	Any word that is also the name of an existing file
	is also turned into a link.
	
	If the file doesn't have an extension of .html, 
	.htm, .gif or .jpg, we try replacing its extension
	with these to find a generated file, e.g. replace
	'diagram.fig' with 'diagram.gif'.  If we still can't
	find a file type we recognise, we still make a link to
	it, but output a warning.
	
	If the target file is an image (determined by file
	extension), the word is replaced
	with an inline image, with HEIGHT and WIDTH attributes
	set if possible.  E.g.  picture.gif -> <IMG SRC="picture.gif"
	HEIGHT=40 WIDTH=50>
	
	If the source word for a local link contains underscores, 
	those underscores are replaced with spaces,
	e.g. long_file_name might translate to
	<A HREF="long_file_name.html>long file name</A>

OUTPUT

	The parsed document will be rendered to HTML,
	and combined with a template document, which
	will contain the common header and footer.

	A collection of parsed documents might also
	be rendered into one larger printable document,
	with a header, footer and separator.
