$_$_CHANGE_POLICY Document author  : John A Fotheringham
$_$_CHANGE_POLICY Document Subject : Tag Manual for JafSoft text conversion utilities
$_$_CHANGE_POLICY Document Company name : JafSoft Limited
$_$_TITLE Tag Manual for JafSoft text conversion utilities
$_$_CHANGE_POLICY Highlight Definition Text        : Yes
$_$_CHANGE_POLICY Bullet Char			   : '-'
$_$_CHANGE_POLICY Minimum TABLE column separation  : 2
$_$_CHANGE_POLICY Default TABLE Header cols        : 1
$_$_CHANGE_POLICY Default TABLE Border size	   : 0
$_$_CHANGE_POLICY Default TABLE cell padding	   : 2
$_$_CHANGE_POLICY Cross-refs at level 		   : 1
$_$_CHANGE_POLICY Preserve underlining of headings : no
$_$_DEFINE_HTML_FRAGMENT HTML_HEADER
<CENTER>
<H2>The "Tag Manual" for JafSoft's text conversion utilities</H2>
<p><font size=-1>The most recent version of this document can always
be found <A HREF="http://www.jafsoft.com/doco/">online</A></font></p>
</CENTER>
<HR NOSHADE>
$_$_END_BLOCK
$_$_DEFINE_HTML_FRAGMENT HTML_FOOTER
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR><TD WIDTH=100><a href="http://validator.w3.org/"><img border=0
        src="vh40.gif" alt="Valid HTML 4.0!" height=31 width=88></a></TD>
    <TD ALIGN="CENTER">Converted from 
      <A HREF="tag_manual.txt">a single text file</A> by <A 
      HREF="http://www.jafsoft.com/asctohtm/">AscToHTM</A><br>
&copy; 1997-2004 John A. Fotheringham
    </TD><TD ALIGN="RIGHT"><A
      HREF="http://www.jafsoft.com/asctohtm/"><IMG
      SRC="a2hlogo.gif" WIDTH=100 HEIGHT=36 BORDER=0
      ALT="Converted by AscToHTM"></A></TD></TR>
</TABLE>
$_$_END_BLOCK

This file was generated by [[VERSION]] from this [[SOURCE_FILE]] on [[TIMESTAMP]]

$_$_CONTENTS_LIST


1 Introduction 

[JafSoft] have produced the following programs

      - [AscToHTM] converts plain text files into HTML files
      - [AscToRTF] converts plain text files into RTF files

These programs share the same text analysis engine, and should do a good
job of understanding the structure of the text document and replicating
it in the target format.

However frequently users will want to have control over how the output looks
and occasionally the text analysis will go wrong.  For that reason the 
software supports

      - a large number of configuration options that act as rules or
        "policies".  These policies may be saved in an external file
        called a policy file, so that the same combination of policies
        can be re-loaded.  The use of policies is described fully in 
	the [Policy Manual].

      - The addition of special tags to the source file which tell the
        program's "pre-processor" how to process the file.

This document describes the tagging system that the software supports.


1.1 Overview of the pre-processor

During the analysis process the software reads the source files line-by-line.
The pre-processor recognises special keywords in two ways :-

      *Directives*

      "Directives" consist of a single line in the source file beginning 
      with the string "$_$_" followed by a recognised keyword and
      any additional "attributes" that the directive supports.  

      *In-line tags*

      In-line tags, as the name implies, can occur anywhere in the source
      lines.  They are enclosed between the special strings "[[OT]]" and
      "[[CT]]".  Between these strings the tag consists of a keyword and
      then any attributes that tag supports.

In both cases the tag or directive cannot be split over multiple lines,
that is directives must be on a line by themselves, and in-line tags must
be wholly contained on a single line.

Examples of a directive and in-line tags are shown below.

$_$_BEGIN_PRE
      $_$_LINERULE 75%

      The BR tag means this text will be broken [[OT]]BR[[CT]] into two lines.
$_$_END_PRE

becomes :-

$_$_LINERULE 75%
The BR tag means this text will be broken [[BR]] into two lines.


Some tags can be expressed in either directive or in-line form.


1.2 Directives

Directives exist on a line by themselves in the source text.  They have the
form

	$_$_<keyword> <attribute_list>

where the "$_$_<keyword>" must occur at the start of the line and the 
<keyword> must be recognised.

If the "$_$_<keyword>" is not at the start of the line, the directive is ignored
and treated as end-user text.  This device has been used to date to aid 
conversion of the software's own documentation to HTML and Windows Help files.

The format of the <attribute_list> depends on the particular tag, but a
general description is given in 1.4.


1.3 In-line tags

In-line tags may occur anywhere within end-user text, but *not* on directive
lines or inside other in-line tags.  In-line tags have the form

	[[OT]]<keyword> <attribute_list>[[CT]]

that is the <keyword> and its <attribute_list> are between "[[OT]]" and "[[CT]]"
delimiters.  Initially the start and end delimiters must lie on the same line 
of the source text.

The <keyword> must be recognised, even if the tag is not yet fully implemented.

Note, the delimiters "[[OT]]" and "[[CT]]" are themselves dynamically 
configurable.  

The format of the <attribute_list> depends on the particular tag, but a
general description is given in 1.4.


1.4 Tag attribute lists

The <attribute_list> should be a comma-delimited set of attribute values.  
The number and types of attributes expected will depend on the tag concerned.

Some tags allow attributes to be optionally omitted, and a default value
used instead.  If the attribute being omitted is not the last on the
list, then a place-saving comma should be supplied.

Examples

	TAG 1,2,3,4	// full list
	TAG 1,,3,4	// argument 2 is missing
	TAG 1,,3,	// arguments 2 and 4 are missing
	TAG 1,,3	// arguments 2 and 4 are missing
	TAG 1		// arguments 2, 3 and 4 are missing

If a *mandatory* argument is missing (one for which no default value is
permitted), a TAG_ERROR will be signalled.

Each attribute in the list will be of a particular type.  Supported types are

      - numeric values (mostly integers)
      - strings (enclosed in quotes (see below)
      - coded lists... e.g. an alignment attribute can take the values
        'L' for Left, 'R' for Right etc.

If a particular attribute value is incorrect for the expected type, then
a TAG_ERROR will be signalled.

String attributes should be be placed in quotes if they contain commas
themselves.  It's probably good practice to place them in quotes in any case.
Quotes within string attributes should be doubled up e.g.

      "This string has the word ""quotes"" in quotes"

becomes

      This string has the word "quotes" in quotes

Here are some examples

	TAG 1,2			// arg 1 is '1', arg 2 is '2'
	TAG ,2			// arg 1 is missing, arg 2 is '2'

	TAG "one",2		// arg 1 is 'one', arg 2 is '2'
	TAG "say one",2		// arg 1 is 'say one', arg 2 is '2'

	TAG "a,b", 2		// arg 1 is 'a,b', arg 2 is '2'
	TAG "say ""one"""", 2	// arg 1 is 'say "one"', arg 2 is '2'

	TAG 			// both arguments missing, defaults will be used
	TAG ,			// both arguments missing, defaults will be used
	TAG ,,			// both arguments missing, defaults will be used


1.5 Error handling

1.5.1 Unrecognised and unimplemented tags

Unrecognised and unimplemented tags will be signalled via messages.  These
messages will be given different severities.  The software allows messages to 
be filtered by severity and type, so in this way the testing and production 
versions of the software can be made to report differently.


1.5.2 Parse errors

All failures to fully parse a tag will be reported.  The actual error recovery
(if any) will vary on a tag-by-tag basis.  Usually the tag will simply be 
ignored, removed from the end-user text and signalled as in error.  Occasionally
a certain default behaviour may be possible.

For example, a failure to fully parse the attribute list of a LINERULE tag 
would probably default to outputting a simple <HR> into the HTML, rather than
completely ignoring the LINERULE request.



1.6 Tagging restrictions

    - Most tags are either directives or in-line tags.  Only a few may
      be used as either.

    - The tag must be wholly contained on a single line in the source file.

      Directives must be on a line by themselves.

      You can have multiple in-line tags on one line, but no single 
      in-line tag may be spread over multiple lines.

    - Nested in-line tags are not allowed



2. Using the pre-processor

The preprocessor was originally introduced to allow users more flexibility 
in the HTML they generate.  

The pre-processor allows [AscToHTM] and [AscToRTF] to be used as 
an authoring tools, as opposed to a simple text conversion or migration tool.  

Preprocessor lines are not normally output to the HTML or RTF generated.
Instead they are used to modify the conversion process in a number of ways.


2.1   Marking up sections of text

The pre-processor can be used to mark sections in your document so that
the program will correctly process them as you wish.

Note:	The software does attempt to spot much user-formatted text
      	automatically, but this is a difficult area and prone to
      	error.  Hence the use of these directives can reduce the
      	error rate on such occasions.

Examples include :-

      *[[POPUP SECTION]]*

      This directive is used to divide the document up into named sections
      that may then be conditionally included/excluded from a particular
      conversion.

      *[[POPUP BEGIN/END_TABLE]]* [[BR]]
      *[[POPUP BEGIN/END_DELIMITED_TABLE]]* [[BR]]
      *[[POPUP BEGIN/END_COMMA_DELIMITED_TABLE]]* [[BR]]
      *[[POPUP BEGIN/END_USER_TABLE]]* *New function*

      These pairs of directives are used to bracket tables of various types
      in the source text.  The software will attempt to detect plain text
      tables, but if this goes wrong adding these commands can correct the
      analysis

      Within these tables you can use other TABLE pre-processor commands
      to tailor the HTML generated (see "[[GOTO The TABLE commands]]").

      *[[POPUP BEGIN/END_CONTENTS]]*

      Used to mark up a contents list in the source document.  The software
      will attempt to automatically detect the presence and location of any 
      contents list in the document, but the algorithm can be problematic,
      and only really works for numbered headings.

      *[[POPUP BEGIN/END_HTML]]*

      Delimits a section of raw HTML code to be copied to the output file
      unchanged.

      *[[POPUP BEGIN/END_CODE]]* [[BR]]
      *[[POPUP BEGIN/END_DIAGRAM]]* [[BR]]
      *[[POPUP BEGIN/END_PRE]]*

      Delimits sections of pre-formatted text.  CODE refers to software samples
      whilst DIAGRAM refers to ASCII art.  PRE is the more general 
      "pre-formatted" text, although currently all 3 have the same 
      implementation.

      *[[POPUP BEGIN/END_IGNORE]]*

      Delimits text that should be ignored.  This could be anything from 
      comments to copyright statements in the original source file that shouldn't
      appear in the converted document.


2.2   Commands that influence the indexing of the document

Certain directives can be used to alter the document properties.  Often these
affect how the document will be searched and indexed.  

In HTML these mostly lead to tags in the <HEAD>..</HEAD> of each page.  Often
these tags produce no visible effect.

In RTF these lead to field in the document properties being filled in.

Examples include :-

      *[[POPUP TITLE]]* [[BR]]
      *[[POPUP DESCRIPTION]]* [[BR]]
      *[[POPUP KEYWORDS]]* [[BR]]
      *[[POPUP STYLE_SHEET]]* (HTML Only)

The DESCRIPTION and KEYWORDS commands may be continued on subsequent lines
provided they also begin with the same $_$_<command> directive.


2.3 Useful one-line pre-processor commands

A large number of one-line directives exist.  Those for tables are listed
the section on [[GOTO The TABLE commands]].  Others include

      *[[POPUP CONTENTS_LIST]]* [[BR]]
      *[[POPUP HTML_LINE]]* [[BR]]
      *[[POPUP INCLUDE]]*  [[BR]]
      *[[POPUP LINERULE]]*  [[BR]]
      *[[POPUP NAVIGATION_BAR]]* [[BR]]
      *[[POPUP TOC]]*


2.4 Useful in-line tags

A large number of in-line tags are available.  These can be used to produce
a number of useful effects.  They include :-

      *[[POPUP BR (line break)]]* [[BR]]
      *[[POPUP GOTO]]* [[BR]]
      *[[POPUP HYPERLINK]]* [[BR]]
      *[[POPUP TIMESTAMP]]* [[BR]]
      *[[POPUP SPACES]]* [[BR]]
      *[[POPUP SUPER and SUB]]* [[BR]]
      *[[POPUP VARIABLE]]*


2.5   The TABLE commands

These directives are used to tailor the HTML generated in any tables
the software creates.  They are placed either

      _At the top of the file_ [[BR]]
      Directives placed here become defaults for the whole file, and will
      replace any policies that have been set (see the section on 
      "Table Generation" in the AscToHTM manual)

      _Inside a BEGIN_TABLE ... END_TABLE section_ [[BR]]
      Directives placed here will apply only to the table marked up by
      these commands (see 7.1.2).

The table commands are described (naturally enough) in the following
table.

$_$_BEGIN_DELIMITED_TABLE
$_$_TABLE_BORDER 0
$_$_TABLE_ALIGN CENTER
$_$_TABLE_CELLSPACING 2
Directive	Value	Effect
--------------------------------------------------------------------------------
[[POPUP TABLE_ALIGN]]	Align	Specifies the alignment of the whole table.

[[POPUP TABLE_BGCOLOR]]	Colour	Colour of background

[[POPUP TABLE_BORDER]]	Number	Size of border.  0 = None

[[POPUP TABLE_BORDERCOLOR]]	Colour	Colour of border

[[POPUP TABLE_CAPTION]]	Text	Table caption.  Added centred at the top

[[POPUP TABLE_CELL_ALIGN]]	Align	Specifies the default alignment of
		cells.  Left, right or center 

[[POPUP TABLE_CELLSPACING]]	Number	Spacing between cells.

[[POPUP TABLE_CELLPADDING]]	Number	Padding inside each cell

[[POPUP TABLE_COLO(U)R_ROWS]]	(none)	If present this specifies that the
		odd and even rows of the table should
		be coloured differently.  See also the
		[[HYPERLINK POLICY,"Colour data rows"]] policy.

[[POPUP TABLE_CONVERT_XREFS]]	(none)	If present, indicates that any section
		cross-references in the table may
		be converted to hyperlinks 
		(see also the policy line
		[[HYPERLINK POLICY,"Convert TABLE X-refs to links"]])

[[POPUP TABLE_EVEN_ROW_COLO(U)R]]	Colour	When data rows are to be coloured
		this specifies the colour of the
		even numbered rows.

[[POPUP TABLE_HEADER_ROWS]]	Number	Number of header rows.  These
		will be placed in <TH> .. </TH> markup

[[POPUP TABLE_HEADER_COLS]]	Number	Number of header columns.
		These will be marked up in bold

[[POPUP TABLE_IGNORE_HEADER]]	(none)	If present, indicates that the first
		few line (i.e. the header) should be ignored 
		when calculating the column structure of the table.
		See also policy [[HYPERLINK POLICY,"Ignore table header during analysis"]]

[[POPUP TABLE_LAYOUT]]	Layout	Explicit structure of table in terms of
		number of columns and their widths.
		See also policy [[HYPERLINK POLICY,"Default TABLE layout"]]

[[POPUP TABLE_MAY_BE_SPARSE]]	(none)	If present, indicates that the TABLE
		may be sparse (see also the policy
		[[HYPERLINK POLICY,"Expect sparse tables"]])

[[POPUP TABLE_MIN_COLUMN_SEPARATION]]	Number	Number of spaces to be taken as a
		column separator when analysing the
		table (see also the policy
		[[HYPERLINK POLICY,"Minimum TABLE column separation"]]).

[[POPUP TABLE_ODD_ROW_COLO(U)R]]	Colour	When data rows are to be coloured
		this specifies the colour of the
		odd numbered rows.

[[POPUP TABLE_WIDTH]]	Text	The width of the table (see also the
		policy [[HYPERLINK POLICY,"Default TABLE width"]])

$_$_END_DELIMITED_TABLE

Colours should be [[GOTO HTML Colours]] which will placed in the 
various attributes of the <BODY> tag and other.  The program simply 
transcribes your value into the output file.


2.6   The CHANGE_POLICY command

      NOTE: 	This feature has the potential to cause mayhem, and as such is offered 
      		to users on a "as is" basis.  That is, we offer no support for getting 
      		this feature to have the effect a user may desire.

      This directive allows you change a particular policy in part of a 
      document.  This is a potentially powerful feature, allowing you to tailor
      the conversion of your file *in different sections of that file*, or
      to embed the policy particular to a file in commands inserted at the top
      of the file itself.

      The syntax of the command line is

      	$_$_CHANGE_POLICY <Policy Line>

      where <Policy_line> is a policy line as it would appear in a policy file,
      and (usually) as it appears in the [Policy Manual].

      For example the following would all be valid directives

$_$_BEGIN_PRE
      	$_$_CHANGE_POLICY Background Colour : red
      	$_$_CHANGE_POLICY Ignore multiple blank lines : Yes
$_$_END_PRE
      
      Although how and when they would take affect will depend on the policy.

      For example, the background colour would only take effect if splitting 
      the file up, and only on the next file generation.  This works, BTW, so
      if anyone wants to split a file into many pages, all different colours,
      then be my guest.
      
      There are a *many* caveats to this behaviour :-

      - *not all policies are supported*

      	Not all policies may be changed in this way.  In particular policies
      	that open other policy files are not supported.  Even if a policy
      	if "changed", it does not follow that changing the policy will have
      	an effect.

      - *analysis policies*

      	It is unlikely that this feature can be sensibly used to influence the
      	analysis of file, other than when placed at the top of the file only.
      	If such a manner it is simply an alternative to using a separate 
      	policy file.

      - *output policies*

      	Output policies are referenced at different times.  Only those that are
      	referenced *after* the line is read from the source file may be
      	influenced, thus things like output file name may have no effect.

      - *toggleable policies*

      	Not all policies once changed, can be changed back.  This is 
      	particularly of policies that contain values to be added to a list.
      	This is an issue that may be addresses in later versions.
      	
      - *unpredictable behaviour*

      	Messing with policies can cause unpredictable behaviour.  For example
      	if you alter the section splitting parameters, then the chances of a 
      	section cross-reference elsewhere in the document being calculated
      	as a correct hyperlink diminishes.

      	*That's why this feature is offered UNSUPPORTED*

      - *readahead buffer*

      	To further complicate matters, the software uses a readahead, write 
	behind buffer which means that you may need to experiment with the 
	placing of your policy change to within 40 lines (the size of the 
	buffer).

      	This problem is alleviated since version [[TEXT 3.2]].


2.7 Definition blocks and variables

Using pre-processor tags you can define "blocks" of text known as 
"definition blocks". 

Definition blocks allow blocks of output to be defined out of sequence, that
is the content is defined in one location, and then may be instantiated at
a number of different locations.

A definition block has the form

$_$_BEGIN_PRE
	$_$_DEFINE_BLOCK <block name>
	..
	text that forms the block
	..
	$_$_END_BLOCK
$_$_END_PRE

The text inside the block may contain in-line tags, but it cannot contain
any other tag directives.

To invoke a block use the [[POPUP EMBED_BLOCK]] or [[POPUP INSERT_BLOCK]] 
commands.

One tag that is particularly useful inside blocks is the [[POPUP VARIABLE]] tag.
You can define variables throughout the document and then quote them inside
a define block.

A possible example of use would be the addition of "page" footers.  You
could define the text that goes inside a page footer, and include in it
a variable called PAGE_NUMBER.  You can then re-define the PAGE_NUMBER and
output a new page boundary with the commands

$_$_BEGIN_PRE
	$_$_DEFINE_VARIABLE PAGE_NUMBER 21
	$_$_INSERT_BLOCK PAGE_FOOTER
$_$_END_PRE

having previously defined a PAGE_FOOTER block.

It should perhaps be pointed out that "pages" are anathema to HTML, but
should you want this feature this is a possible implementation.


2.8 HTML colours

Some tags accept colour values.  These values should be HTML colours 
which - for example - may be placed in the various attributes of the <BODY> 
tag.  

You can enter any value acceptable to HTML.  Normally a value is expressed as 
a 6-digit hexadecimal value in the range 000000 (black) to FFFFFF (white), but 
certain colours such as "white", "blue", "red" etc may also be recognised 
by HTML.  The software (AscToHTM) simply transcribes your value into the 
output file.  The list of colours recognised in the HTML standard is

$_$_BEGIN_TABLE
$_$_TABLE_HEADER_COLS 0
$_$_TABLE_BORDER 1
$_$_TABLE_ALIGN C
	Colour		HTML Hex value
	--------------------------
	Black		#000000
        Silver		#C0C0C0
        Gray		#808080
        White		#FFFFFF
        Maroon		#800000
        Red		#FF0000
        Purple		#800080
        Fuchia		#FF00FF
        Green		#008000
        Lime		#00FF00
        Olive		#808000
        Yellow		#FFFF00
        Navy		#000080
        Blue		#0000FF
        Teal		#008080
        Aqua		#00FFFF
$_$_END_TABLE

Only these values will be converted by the software to the equivalent names.
Other names exist outside the standard which may not be universally supported.


2.9 English/American spellings

As far as possible tags support both British English and American English
spellings.  This mainly occurs with the word "colour" (or "color"), so for 
example the directives

      $_$_TABLE_ODD_ROW_COLOUR ....
and
      $_$_TABLE_ODD_ROW_COLOR ....

are equivalent.


3 Using HTML fragments

3.1 Overview

_HTML fragments only apply to HTML generation (obviously)_

The "HTML fragments" feature allows you to define a block of HTML that you 
can then embed in your document at key locations.  These fragments are 
pure HTML that gets transcribed into the output files, but they may contain 
[[GOTO "fragment tags"]] that will be replaced by suitable values each time 
the fragment is used.

Most fragments use reserved names, that is they have a particular meaning 
to the program.  If you define fragments with these names they will be used 
instead of the HTML that is generated by default.

Currently only fragments with reserved names are used by the software.
The ability to define and use your own fragments names may be added in 
later versions of the software.

You can choose to define empty fragments.  This can be done either by
literally defining a fragment with no HTML in it, or by issuing a
RESET_HTML_FRAGMENT command - see [[POPUP "DEFINE_HTML_FRAGMENT and RESET_HTML_FRAGMENT"]]

If an empty HTML fragment is defined then no HTML will be generated.  If 
the fragment name is a reserved name then the result is to suppress that 
particular feature.  

For example the command

      $_$_RESET_HTML_FRAGMENT NAVBAR_TOP 

would cause the navigation bar at the top of each page to be suppressed when
splitting large documents into several small pages.

HTML fragments may be defined either in the source text, or in a separate 
"HTML fragments file".  This file may then be selected via the policy
[[HYPERLINK POLICY,"HTML fragments file"]].  Only the fragments themselves
will be read from this file, everything else will be ignored, leaving you
free to add your own comments to this file between the fragment definitions.

If you don't want to set the policy you can get the same effect by using the
[[POPUP INCLUDE]] command as follows

      $_$_INCLUDE <fragments file>

to your source file near the top.  This will copy the fragments file into
your source text, so in this case you should include no other text in this 
file as it will appear in the output.

You may, if you wish, re-define the HTML fragment later in the file.  This 
will take effect from that point onwards.  For example if you redefine the 
HORIZONTAL_RULE fragment to be an image, you could arrange for this image
to change for different sections of your document.


3.2 How to define a HTML fragment

Simply use pre-processor commands as follows

$_$_BEGIN_PRE
      $_$_DEFINE_HTML_FRAGMENT <name>
      ...
      ...<your HTML with embedded "fragment tags">
      ...
      $_$_END_BLOCK
$_$_END_PRE

For example,

$_$_BEGIN_PRE
      $_$_DEFINE_HTML_FRAGMENT NAVBAR_BOTTOM

      <A HREF="[[OT]]PREV_PAGE[[CT]]"><IMG SRC="prev.gif"></A>
      <A HREF="[[OT]]NEXT_PAGE[[CT]]"><IMG SRC="next.gif"></A>

      $_$_END_BLOCK
$_$_END_PRE

could define a navigation bar for the bottom of each page which adds a
hyperlink to the previous and next page which is added to some .gif.  
The [[GOTO fragment tags]] [[OT]]PREV_PAGE[[CT]] and [[OT]]NEXT_PAGE[[CT]] will be 
replaced by the correct URLs.

$_$_BEGIN_PRE
      $_$_RESET_HTML_FRAGMENT NAVBAR_TOP
$_$_END_PRE
or
$_$_BEGIN_PRE
      $_$_DEFINE_HTML_FRAGMENT NAVBAR_TOP
      $_$_END_BLOCK
$_$_END_PRE

both define an "empty" top navigation bar, thereby suppressing the generation
of a navigation bar at the top of each page.


3.3 Fragment tags

Within HTML fragments special "fragment tags" are supported.  These tags have
the same overall format as the more general pre-processor tags, but are only
supported inside HTML fragments.

The following tags are supported


3.3.1 Tags for navigation bar fragments

$_$_BEGIN_TABLE
      Tag			Description
      =========================================================================
      PREV_PAGE			URL of previous page.  If no pervious page then URL 
      				of *this* page

      CURRENT_PAGE		URL of the current page.  Can be useful if
      				you want to construct a NOFRAMES link to the
      				current page.

      NEXT_PAGE			URL of next page.  If no next page then the URL of 
      				*this* page.

      CONTENTS_TOP		URL of page containing contents list

      CONTENTS_NEXT_SECTION	As above - but linked to an anchor for the 
      				next section in the contents list.
$_$_END_TABLE

3.3.2 Tags for horizontal rule fragments

$_$_BEGIN_TABLE
      Tag		Description
      =========================================================================
      RULEWIDTHPC	The calculated ruler width expressed as a percentage.  
      			Often the program will detect a line, and will set it
	    		as a <HR> tag of the appropriate percentage width.  
      			This is that value.

      RULEWIDTH		The calculated ruler width.  This will be the 
      			percentage width expressed for a default 800 pixel 
      			wide screen.

      RULEHEIGHT	The ruler height.  Not usually varied unless supplied 
      			as part of a [[POPUP LINERULE]] tag.

      RULEALIGN		The ruler alignment.  This may sometimes be set to LEFT 
      			if a less that 100% rule is being generated, or it 
      			may be set to some other value by a user-supplied
	    		[[POPUP LINERULE]] tag.
$_$_END_TABLE

The above values are all supplied ready to be used as attribute values.  As 
such they should normally be enclosed in quotes in your HTML fragment.  If
you're using an <IMG> tag and want to capture the width, use the RULEWIDTH
value.  If you're generating an <HR> tag we recommend the RULEWIDTHPC percentage
value instead.


3.3.3 Tags for frame fragments

*New function*

Currently there is only one fragment tag used inside frames fragments :-

	NOFRAMES_URL	This is the URL used by default for any NOFRAMES
			link.  Typically you'd use this inside a NOFRAMES_LINK
			fragment to link to the same URL as the default
			NOFRAMES link would, while adding your own text and
			decoration for the link.


3.3.4 Tags for Heading fragments

*New function*

The following tags may be used inside the various Heading tag fragments

      	HEADER_TEXT	The text part of the heading

      	HEADER_LEVEL	The heading level (1,2,3...).  Note, this is the
      			*logical* heading level.  The default markup might
      			use a different <Hn> tag because these values are
      			limited in range to ensure text is a sensible size
      			(<H1> is too big, <H4> is too small etc).


3.3.5 Tags for Table of Contents fragments

*New function*

The following tags may be used inside the various TOC line tag fragments

      	TOC_TEXT	The text part of the TOC line

      	TOC_LEVEL	The TOC level (1,2,3...)

      	TOC_URL		The URL for this TOC line


3.4 Reserved HTML fragment names

Here are the reserved HTML fragment names recognised by the software, and
their effect on the HTML generated.

3.4.1 Navigation bar fragments

$_$_BEGIN_TABLE
      NAVBAR_TOP_FIRST		The navigation bars output at the top of the
      NAVBAR_TOP		first, general or last pages.  Usually the first and
      NAVBAR_TOP_LAST		last navigation bars may wish to omit the previous
    				or next links (since no such page exists).  If the
      				"_FIRST" and "_LAST" fragments are not defined, the
      				"NAVBAR_TOP" fragment will be used instead.

      NAVBAR_MIDDLE		Any navigation bar output in the middle of a page
      				as a result of a [[POPUP NAVIGATION_BAR]] tag.

      NAVBAR_BOTTOM_FIRST	As for the "NAVBAR_TOP" fragments, but this time	
      NAVBAR_BOTTOM		at the bottom of generated pages.
      NAVBAR_BOTTOM_LAST	
$_$_END_TABLE

3.4.2 The Horizontal rule fragment

      HORIZONTAL_RULE   The horizontal ruler.  Normally this is
      			just <HR>, but you can change that by
      			defining a HTML fragment of this name, e.g. to
      			use an <IMG> tag (see [[GOTO A sample HTML fragments file]]).


3.4.3 Table of contents fragments

*Updated in version [[TEXT 4.2]]*

      These fragments can be used to tailor the appearance of a generated
      contents list.

      START_TOC		A fragment to be output before any generated
			table of contents.  If not defined the default 
			behaviour is to output the title "Table of Contents"

      END_TOC		A fragment to be output after any generated table
			of contents.  If not defined the default behaviour
			is to simply put out a horizontal rule <HR>

      TOC_LINE_<n>	A fragment to be output for TOC contents lines
      			at heading level <n> (<n> = 1,2,3...)

      TOC_LINE		The default fragment to be used for TOC content lines
      			if the specific fragment TOC_LINE_<n> is not defined

When create TOC_LINE fragments, you will almost certainly want to use
the TOC_TEXT and TOC_URL fragment tags (see [[POPUP Tags for Table of Contents fragments]]).


3.4.4 HTML headers, footers and JavaScript fragments

      The program previously supported the insertion of HTML at the start
      and end of each HTML page generated through the policies

	[[HYPERLINK POLICY,"HTML header file"]]
	[[HYPERLINK POLICY,"HTML footer file"]]
	[[HYPERLINK POLICY,"HTML script file"]]

      The new fragments HTML_HEADER, HTML_FOOTER and HEAD_SCRIPT provide 
      exactly the same functionality.

      The use of fragments is encouraged over that of the previous policies,
      so where both are defined, the fragment will be used (e.g. a HTML_HEADER
      fragment will override a "HTML header file" policy value).


3.4.5 HTML header and footers (inside FRAMES) fragments

      A number of fragments can be used to control the creation of header
      and footer FRAMES, and the creation of headers and footers inside
      the main frame.  The use of these fragments depends on the values
      of the policies

	[[HYPERLINK POLICY,"Use main header in header frame"]]
	[[HYPERLINK POLICY,"Use main footer in footer frame"]]
 
      which can be used to promote a HTML header/footer from the top of
      each HTML page into a frame by itself.  This allows the same policy
      file to be used to generate a non-FRAMES set of pages with headers
      and footers on each page, and also a FRAMES set of pages with the
      same headers and footers now permanently on display in their own
      frames at the top and bottom of the screen.

      The following fragments can be used to define the contents of particular
      frames :-
 
      HEADER_FRAME	If defined, this fragment will be used as the
			contents of a header frame at the top of the screen

      FOOTER_FRAME	If defined, this fragment will be used as the 
			contents of a footer frame at the bottom of the
			screen

      NOFRAMES_LINK	If defined, this fragment will be used in place
			of any NOFRAMES link that is created by default.
		        You would most likely use this with the NOFRAMES_URL
			fragment tag to define alternative text on the link.

      CONTENTS_FRAME	If defined, this fragment will be used as the contents
			of the "contents" frame on the left of the screen.
			If not defined the "contents" frame will contain a 
			generated contents list

      MAIN_FRAME_FOOTER If defined, this fragment will be used as the
      			HTML footer of each page that appears in the 
			main frame.  If defined this will override any 
			HTML_FOOTER fragment, or value defined via policy file.

      MAIN_FRAME_HEADER If defined, this fragment will be used as the
      			HTML header of each page that appears in the 
			main frame.  If defined this will override any 
			HTML_HEADER fragment, or value defined via policy file.


3.4.6 Heading fragments

*New function*

Where headings are detected in the program, you can use the following
HTML fragments

      HTML_HEADER_LINE_<n>	The fragment to be used for headings
      				of level <n> (<n> = 1, 2 3...)

      HTML_HEADER_LINE		The default fragment to be used for
      				headings if there isn't a specific
      				HTML_HEADR_LINE_<n> for the value of <n>
      				involved.

The default markup would be to place the heading text in <Hn> tags.  Using the
[[POPUP Tags for Heading fragments]] you could reproduce this in your own
fragments as follows

      <H[[OT]]HEADER_LEVEL[[CT]]>[[OT]]HEADER_TEXT[[CT]]</H[[OT]]HEADER_LEVEL[[CT]]>

e.g. if the heading was "Introduction" and this was a level 1 heading, this
would become

      <H1>Introduction</H1>


3.5 A sample HTML fragments file

The following sample fragments file does the following

    - Defines a HORIZONTAL_RULE fragment to use an image in place of
      the <HR> tag.  The image uses the HTML fragment tags RULEALIGN and
      RULEWIDTH to take on the necessary alignment and size.

    - Defines a HEADER_FRAME that contains a title and link to the home 
      page, both centred on the page.  This fragment will only be used when
      generating a set of FRAMES.

    - Does a reset on the NAVBAR_BOTTOM fragment.  This effectively defines
      an empty fragment whose effect is to suppress the navigation bar usually
      put at the bottom of each page when splitting a large file into sections.

$_$_BEGIN_PRE
      !----- sample HTML fragments file 
      
      Comments in this file (like these) are ignored if the file is selected via the
      "HTML fragments file" policy.  
      
      !----- Horizontal rules 
      
      ! Here's a redefinition of the horizontal rules <HR> that the program generates.
      ! I'm replacing them by an image, but I'm capturing the (pixel) width and fixing
      ! the height (otherwise the image would scale).
      !
      ! Within this fragment I'm using the [[OT]]RULEALIGN[[CT]] and [[OT]]RULEWIDTH[[CT]] HTML
      ! fragment tags to pick up the alignment and width appropriate for the rule
      ! when the fragment is used.
      !
      ! NOTE, not all <HR> tags created by the program are currently overridden in
      !       this way.
      
      $_$_DEFINE_HTML_FRAGMENT HORIZONTAL_RULE
      <DIV ALIGN="[[OT]]RULEALIGN[[CT]]">
      <IMG SRC="HR.GIF" HEIGHT=4 WIDTH="[[OT]]RULEWIDTH[[CT]]"><BR>
      </DIV>
      $_$_END_BLOCK
      
      !----- Frame headers 
      
      $_$_DEFINE_HTML_FRAGMENT HEADER_FRAME
      <DIV ALIGN="CENTER">
      <H2>header frame</H2>
      <A HREF="http://www.jafsoft.com/">Visit the Jafsoft home page!</A>
      </DIV>
      <HR NOSHADE>
      $_$_END_BLOCK
      
      !----- bottom navigation bars 

      ! I don't want any bottom navigation bars so issue a reset command.
      ! I could just as easily have defined an "empty" fragment

      $_$_RESET_HTML_FRAGMENT NAVBAR_BOTTOM

$_$_END_PRE      

The HTML fragments file used on this document is html_fragments.inc


4 Complete TAG list

ALLOW and DISALLOW
==================

Type:		Directive
Description:	Toggles on and off various analysis possibilities
Applies to:	Analysis.
See policy:	(none)

*New function*

Syntax:

$_$_BEGIN_PRE
	ALLOW     <comma-separated list of keywords>
	DISALLOW  <comma-separated list of keywords>
$_$_END_PRE

The software will automatically try to detect various typographical features.
You can turn this behaviour on and off in different sections by using the 
ALLOW and DISALLOW commands.  This can be used, for example, to prevent a 
numbered list being wrongly detected as a numbered heading and vice versa.

The recognised keywords are as follows

$_$_BEGIN_TABLE
	Headings	This enables/disable the search for lines that could be
			treated as headings.

	Lists		This enables/disables the search for lines that could
			be regarded as list items (either unordered bullets, or
			alphabetic or numeric list points)

	All		Set (enable) all of the above

	Reset		Reset (disable) all of the above
$_$_END_TABLE

In each case the tag will simply add or subtract from the current list of 
allowable features.  To aid control, two special keywords "all" and "reset" 
are available for inclusion in the list.  "Reset" will disable all options, 
thus

$_$_BEGIN_PRE
	$_$_ALLOW reset, Headings
$_$_END_PRE

will have the effect of disabling everything (the "reset") and then adding 
"Headings" to the allowed list.  In this respect "ALLOW all" and "DISALLOW 
reset" are identical commands.

Below is an example in which the DISALLOW tag is used to prevent numbered lines
being regarded as lists or headings.  The ALLOW tag at the end switched back to
default behaviour,, so if there are any lists of numbered headings elsewhere 
in the document they will still be detected.

$_$_BEGIN_PRE
	$_$_DISALLOW headings
	...
	1. Whatever this line is, it isn't a heading
	...
	$_$_DISALLOW headings,lists
	...
	2. Whatever this line is, it isn't a heading *or* a list item
	...
	$_$_ALLOW reset
	...
	3. This *may* be interpretted as either a heading or list item
	...
$_$_END_PRE


BASEHREF
========

Type:		Directive
Description:	Specifies URL that is used to resolve relative URLs
Applies to:	Hyperlinks. HTML only
See policy:	[[HYPERLINK POLICY,"Document Base URL"]]

Syntax:

$_$_BEGIN_PRE
	$_$_BASEHREF <base URL to be used>
$_$_END_PRE

_Ignored in RTF conversions_

In HTML the URL is added to a BASE tag inserted into the <HEAD> 
section of the output page(s) as follows :-

      	<BASE HREF="url">

This tag is used to specify the base URL against which all relative
URLs should be resolved.  You might want to use this if you are going
to copy the page to a mirror location, but not copy the pages referred to
in the relative links.

The presence of a BASEHREF pre-processor command overrides any base URL
specified via a [[HYPERLINK POLICY,"Document base URL"]] policy line.


BEGIN/END_ASCII
===============

Type:        	Directive
Description: 	Delimits a section of text to appear in any "de-tagged" text
Applies to:	All (ignored)
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
      $_$_BEGIN_ASCII
      ...
      (text to be shown only in de-tagged ASCII)
      ...
      $_$_END_ASCII
$_$_END_PRE

This markup can be used to delimit a section of text that will be ignored
when converting to HTML or RTF, but to be included whenever a "de-tagged"
version of the source file is produced.

The de-tag utility creates a plain text version of the source file, e.g.
for posting on Usenet.  This tag allows authors to supply an alternative
in the text file something that might be generated during HTML generation.

For example the sequence

$_$_BEGIN_PRE
	$_$_CONTENTS_LIST
	$_$_BEGIN_ASCII
	...
	hand-written contents list
	...
	$_$_END_ASCII
$_$_END_PRE

would allow a generated contents list to be placed in the HTML version,
but a hand-written contents list to appear in its place in the text version.


BEGIN/END_CODE
==============

Type:		Directive
Description:	Delimits the start and end of a code sample.
Applies to:	Text analysis
See policy:	[[HYPERLINK POLICY,"Expect code samples"]]

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_CODE
	...
	(lines of code)
	...
	$_$_END_CODE
$_$_END_PRE

The BEGIN_CODE ... END_CODE directives are used to bracket a piece
of sample code in the source text.

In HTML this will either be rendered in <PRE> ... </PRE> markup or
<CODE> ... </CODE> markup (see the discussion about the policy 
[[HYPERLINK POLICY,"Use <CODE>..</CODE> markup"]] to see why the former
is used as default).


BEGIN/END_COMMA_DELIMITED_TABLE	
===============================

Type:		Directive
Description:	Delimits a table of comma-delimited data
Applies to:	Text analysis
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_COMMA_DELIMITED_TABLE
	...
	(lines of comma-delimited data)
	...
	$_$_END_COMMA_DELIMITED_TABLE
$_$_END_PRE

The BEGIN_COMMA_DELIMITED_TABLE ... END_COMMA_DELIMITED_TABLE directives
can be used to delimit a series of comma-delimited data values that should
be interpreted as a table (e.g. data originally exported from a
spreadsheet such as Excel)

The presence of these directives overrides any value set in the
[[HYPERLINK POLICY,"Attempt table generation"]] policy 


BEGIN/END_CONTENTS
==================

Type:		Directive
Description:	Delimits a contents list in the original source file
Applies to:	Text analysis.  Mainly HTML generation.
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_CONTENTS
	...
	(original contents list)
	...
	$_$_END_CONTENTS
$_$_END_PRE

The BEGIN_CONTENTS ... END_CONTENTS directives are used to bracket a
contents list in the source document.  The program will attempt to 
automatically detect the presence and location of any contents list 
in the document, but the algorithm can be problematic.

Use this markup only when the document contains a contents list that
the program fails to detect correctly.


BEGIN/END_DELIMITED_TABLE
=========================

Type:		Directive
Description:	Delimits a table of delimited data
Applies to:	Text analysis
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_DELIMITED_TABLE [<delimiter>]
	...
	(lines of delimited data)
	...
	$_$_END_DELIMITED_TABLE
$_$_END_PRE

where

      <delimiter>	The delimiter character to use.  If omitted
      			the default is tab-delimited.  The delimiter
      			can be any character except a comma.  For 
      			comma-delimited tables use the 
      			[[GOTO BEGIN/END_COMMA_DELIMITED_TABLE]] command instead

The BEGIN_DELIMITED_TABLE ... END_DELIMITED_TABLE directives
can be used to delimit a series of delimited data values that should
be interpreted as a table (e.g. data originally exported from a
spreadsheet such as Excel)

The presence of these directives overrides any value set in the
[[HYPERLINK POLICY,"Attempt table generation"]] policy 


BEGIN/END_DIAGRAM
=================

Type:		Directive
Description:	Delimits the start and end of an ASCII diagram
Applies to:	Text analysis
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_DIAGRAM
	...
	(ASCII diagram)
	...
	$_$_END_DIAGRAM
$_$_END_PRE

The BEGIN_DIAGRAM ... END_DIAGRAM directives are used to bracket a piece
of Ascii art or text diagram in the source text.

In HTML this will be rendered in <PRE> ... </PRE> markup.


BEGIN/END_HTML
==============

Type:		Directive
Description:	Delimits some HTML to be copied to the output
Applies to:	HTML generation only
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_HTML
	...
	(block of HTML code)
	...
	$_$_END_HTML
$_$_END_PRE

$_$_BEGIN_HTML
      <IMG SRC="a2hdoco1.jpg" BORDER=0 ALIGN=RIGHT
       HEIGHT=160 WIDTH=160 ALT="AscToHTM">
$_$_END_HTML

The BEGIN_HTML ... END_HTML directives are used to bracket actual
HTML in the source document.

The bracketed HTML will be transcribed to the output file unconverted.

This device will allow you to embed images, tables and other HTML
constructs not normally generated by AscToHTM.

This is how the image to the right has been added to the HTML version of
this document.

If you simply wish to insert a single line of HTML, the [[POPUP HTML_LINE]]
tag offers a more compact form.

For in-line HTML use the [[POPUP HTML]] in-line tag.


BEGIN/END_IGNORE
================

Type:        	Directive
Description: 	Delimits a section of input to be ignored
Applies to:	All (ignored)
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
      	$_$_BEGIN_IGNORE
      	...
      	(text to be ignored)
      	...
      	$_$_END_IGNORE
$_$_END_PRE

This markup can be used to delimit a section to be wholly ignored.  Any
markup and tags in the ignored section will have no effect.


BEGIN/END_PRE
=============

Type:		Directive
Description:	Delimits a region of pre-formatted ASCII text
Applies to:	Text analysis
See policy:	[[HYPERLINK POLICY,"Minimum automatic <PRE> size"]]

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_PRE
	...
	(lines of pre-formatted ASCII text)
	...
	$_$_END_PRE
$_$_END_PRE

The BEGIN_PRE ... END_PRE directives are largely replaced by the
BEGIN/END_TABLE, BEGIN/END_CODE and BEGIN/END_DIAGRAM directives.  They 
are maintained for backwards compatability, and have the same effect as 
the BEGIN/END_DIAGRAM commands


BEGIN/END_TABLE
===============

Type:		Directive
Description:	Delimits a plain text TABLE
Applies to:	Text analysis
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_TABLE
	...
	(plain text table with data all aligned)
	...
	$_$_END_TABLE
$_$_END_PRE

The BEGIN_TABLE ... END_TABLE directives are used to bracket a
plain text table in the source text.  The program will then attempt to 
analyse this table as best it can.

This is explained more in the [AscToTab Doco].

Inside this section you can add other TABLE pre-processor commands
to tailor the HTML generated (see [[GOTO The TABLE commands]]).

BEGIN/END_USER_TABLE
====================

Type:		Directive
Description:	Delimits a user-tagged table
Applies to:	Text analysis
See policy:	(none)

*New function*

Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_USER_TABLE
	...
	$_$_COLUMN_DETAILS ...

	$_$_NEW_ROW
	$_$_NEW_CELL
	... contents of cell (1,1)
	$_$_NEW_CELL
	... contents of cell (1,2)

	$_$_NEW_ROW
	$_$_NEW_CELL
	... contents of cell (2,1)
	$_$_NEW_CELL
	... contents of cell (2,2)
	...
	$_$_END_TABLE
$_$_END_PRE

The BEGIN_USER_TABLE ... END_TABLE directives are used to bracket a
series of tags that describe in detail the layout of a table.  The 
tags used inside the section are

	$_$_COLUMN_DETAILS
	$_$_NEW_ROW
	$_$_NEW_CELL

This approach is only really suitable for use when the files being
converted by AscToRTF are themselves being generated by a software
package that already knows the table structure.

Here's a sample of a user-tagged table (with blank lines added for clarity) :-

$_$_BEGIN_PRE
	$_$_BEGIN_USER_TABLE C,1 in
	$_$_COLUMN_DETAILS 1,,,L, 2 in
	$_$_COLUMN_DETAILS 2,,,C, 1 ins
	$_$_TABLE_BORDER 1

	$_$_NEW_ROW HEAD
	$_$_NEW_CELL
	Substance (units)
	$_$_NEW_CELL
	Year 
	Sampled

	$_$_NEW_ROW DATA
	$_$_NEW_CELL
	Alpha emitters (pCi/L)      
	$_$_NEW_CELL
	1999 

	$_$_NEW_ROW DATA
	$_$_NEW_CELL
	Asbestos (MFL)              
	$_$_NEW_CELL
	1993
	$_$_END_TABLE
$_$_END_PRE

Here's how this table appears when converted into the current format

$_$_BEGIN_USER_TABLE C,1 in
$_$_COLUMN_DETAILS 1,,,L, 2 in
$_$_COLUMN_DETAILS 2,,,C, 1 ins
$_$_TABLE_BORDER 1
$_$_NEW_ROW HEAD
$_$_NEW_CELL
Substance (units)
$_$_NEW_CELL
Year 
Sampled
$_$_NEW_ROW DATA
$_$_NEW_CELL
Alpha emitters (pCi/L)      
$_$_NEW_CELL
1999 
$_$_NEW_ROW DATA
$_$_NEW_CELL
Asbestos (MFL)              
$_$_NEW_CELL
1993
$_$_END_TABLE

See also:-

- [[goto COLUMN_DETAILS]]
- [[goto NEW_ROW]]
- [[goto NEW_CELL]].


BR (line break)
===============

Type:        	In-line
Description: 	Signals a forced line break
Applies to:	HTML and RTF generation
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	[[OT]]BR[[CT]]
$_$_END_PRE

This tag has no attributes.


CHANGE_POLICY
=============

Type:		Directive
Description:	Changes one of the program's "policies"
Applies to:	All
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_CHANGE_POLICY <policy text> : <policy vale>
$_$_END_PRE

where <Policy_text> and <policy value> form a policy line as it would 
appear in a policy file, and (usually) as it appears in the [Policy Manual].

NOTE: 	This feature has the potential to cause mayhem, and as such is offered 
	to users on a "as is" basis.  That is, we offer no support for getting 
      	this feature to have the effect a user may desire.

This directive allows you change a particular policy in part of a 
document.  This is a potentially powerful feature, allowing you to tailor
the conversion of your file *in different sections of that file*, or
to embed the policy particular to a file in commands inserted at the top
of the file itself.

For example the following would all be valid directives

$_$_BEGIN_PRE
      	$_$_CHANGE_POLICY Background Colour : red
      	$_$_CHANGE_POLICY Ignore multiple blank lines : Yes
$_$_END_PRE
      
Although how and when they would take affect will depend on the policy.

For example, the background colour would only take effect if splitting 
the file up, and only on the next file generation.  This works, BTW, so
if anyone wants to split a file into many pages, all different colours,
then be my guest.
      
There are a *many* caveats to this behaviour :-

      - *Not all policies are supported*

      	Not all policies may be changed in this way.  In particular policies
      	that open other policy files are not supported.  Even if a policy
      	if "changed", it does not follow that changing the policy will have
      	an effect.

      - *analysis policies*

      	It is unlikely that this feature can be sensibly used to influence the
      	analysis of file, other than when placed at the top of the file only.
      	If such a manner it is simply an alternative to using a separate 
      	policy file.

      - *output policies*

      	Output policies are referenced at different times.  Only those that are
      	referenced *after* the line is read from the source file may be
      	influenced, thus things like output file name may have no effect.

      - *toggleable policies*

      	Not all policies once changed, can be changed back.  This is 
      	particularly of policies that contain values to be added to a list.
      	This is an issue that may be addresses in later versions.
      	
      - *unpredictable behaviour*

      	Messing with policies can cause unpredictable behaviour.  For example
      	if you alter the section splitting parameters, then the chances of a 
      	section cross-reference elsewhere in the document being calculated
      	as a correct hyperlink diminishes.

      	*That's why this feature is offered UNSUPPORTED*

      - *readahead buffer*

      	To further complicate matters, the software uses a readahead, write 
	behind buffer which means that you may need to experiment with the 
	placing of your policy change to within 40 lines (the size of the 
	buffer).

      	This problem is alleviated since version [[TEXT 3.2]].


COLUMN_DETAILS
==============

Type:       	Directive
Description: 	Defines a column in a user-tagged table
Applies to:	Tagged table generation inside a BEGIN/END_USER_TABLE section
See policy:	(none)

*New function*

Syntax:      

$_$_BEGIN_PRE
	$_$_COLUMN_DETAILS <col_no>,<align>,<width>
$_$_END_PRE

where

$_$_BEGIN_TABLE
	<col_no>	This is the column number, starting at 1

	<align>		This is the alignment of data in this column.
			If omitted this will be auto-detected, but you can
			choose to set it to L(eft), R(ight) or C(enter)

	<width>		The width of the column.  If omitted the width will
			be calculated.  As with the <margin> on the table
			the width can be specified in points, inches or 
			centimetres.  If a width is set too narrow, it may
			be ignored.
$_$_END_TABLE

In a user tagged table section BEGIN/END_USER_TABLE the COLUMN_DETAILS commands
are used to define characteristics of each column in the table.

See also :-

- [[goto BEGIN/END_USER_TABLE]]
- [[goto NEW_ROW]]
- [[goto NEW_CELL]]


CONTENTS_LIST
=============

Type:       	Directive or in-line, but better as a directive.
Description: 	Defines the location to place the contents list (if any).  By
      	     	default the contents list is placed at the top of the document
      	     	before any other end-user text.
Applies to:	Mostly HTML generation
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
        $_$_CONTENTS_LIST <number_levels>,<Style>,<Range>, _More to be defined_
$_$_END_PRE

where,

$_$_BEGIN_TABLE
      <number_levels>	number of levels of heading to be shown in the list 
      			1,2,3... A value of "0" means all.  

      			The default value will be 0.

      <Style>		Style of contents list

			  1	- traditional list (default)
			  2	- navigation bar

			The default value will be 1.

      <Range>		Range of headings to include in the list

			  0	- All (default)
			  1	- All bar first
			  2	- Only those in current chapter
			  3	- Only those in current section
			  
$_$_END_TABLE


DEFINE/END_BLOCK and RESET_BLOCK
================================

Type:        	Directive
Description: 	Delimits a definition block
Applies to:	Document construction
See policy:	(none)


Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_BLOCK <block_name>,<scope>
      	...
      	Block of lines
      	...
	$_$_END_BLOCK
$_$_END_PRE

and

      	$_$_RESET_BLOCK <block_name>,<scope>

where

$_$_BEGIN_TABLE
	<block_name>	The name used to refer to this block.  Block names
			may be reused, in which case the blocks will be
			"scoped" so that required block can be resolved.

	<scope>		The "scope" of this block.  By default blocks are
			scoped to be document wide.  If the same name block
			is defined multiple times then this will determine 
      			the range of document to which this variant of 
      			the block will apply.

      			The Scope will be a list of keywords with one keyword
      			taken from each of the following sets.  If no keyword
      			is found, the set's default will be used.  If multiple
      			keywords from the same set are found, and error will
      			be reported.

      			Range:

      				GLOBAL (default)

      			Application to pages:

      				ALL_PAGES (default)
      				ODD_PAGES_ONLY
      				EVEN_PAGES_ONLY

$_$_END_TABLE

The DEFINE_BLOCK...END_BLOCK delimits a definition block.  Such blocks may 
be instantiated by issuing [[POPUP INSERT_BLOCK]] or [[POPUP EMBED_BLOCK]]
commands anywhere in the document.

The RESET_BLOCK tag may be used to effectively cancel a previously defined
block.  

If you define two blocks of the same name with the GLOBAL scope, the first
will definition will apply up until the location of the second definition.


DEFINE_HTML_FRAGMENT and RESET_HTML_FRAGMENT
============================================

Type:        	Directive
Description: 	Delimits an HTML "fragment" (see [[GOTO "Using HTML Fragments"]])
Applies to:	HTML Document generation only
See policy:	(none)


Syntax:

$_$_BEGIN_PRE
	$_$_BEGIN_HTML_FRAGMENT <fragment_name>,<scope>
      	...
      	Fragment of HTML which may include "fragment" tags
      	...
	$_$_END_BLOCK
$_$_END_PRE

and

      	$_$_RESET_HTML_FRAGMENT <fragment_name>,<scope>

where

$_$_BEGIN_TABLE
	<fragment_name>	The name used to refer to this fragment.  fragment names
			may be reused, in which case the fragments will be
			"scoped" so that required fragment can be resolved.

	<scope>		The "scope" of this fragment.  Same meaning as that
			explained in [[POPUP DEFINE/END_BLOCK and RESET_BLOCK]].
$_$_END_TABLE

The DEFINE_HTML_FRAGMENT...END_BLOCK delimits a fragment of HTML.  Certain
fragment names have special meanings that indicate the HTML fragment is to
be used to override the "standard" HTML generated by the software.

The RESET_HTML_FRAGMENT tag may be used to effectively cancel a 
previously defined fragment.  If a reserved fragment name is reset this
will have the effect of suppressing the generation of that HTML.

See also [[GOTO "Using HTML fragments"]]


DEFINE_VARIABLE
===============

Type:        	Directive
Description: 	Defines a variable value
Applies to:	Document construction
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_DEFINE_VARIABLE <name>,<value>,<scope>
$_$_END_PRE

where

	<name>		The name by which the variable is to be known.

	<value>		The (text) value for the variable

	<scope>		The scope for the variable.


Defines a variable value.  This value may be substituted into the document
text wherever a matching [[POPUP VARIABLE]] tag is used.


DESCRIPTION
===========

Type:		Directive
Description:	Specifies the document's description
Applies to:	HTML and RTF generation, but differently
See policy:	[[HYPERLINK POLICY,"Document description"]]

Syntax:

$_$_BEGIN_PRE
	$_$_DESCRIPTION <Description on rest of line>
$_$_END_PRE

You can repeat this directive over several lines, in which case the descriptions
will be concatenated.  This allows you to write multi-line descriptions making
your source file easy to read.

In RTF the description forms part of the document properties.

In HTML the description is added to a META tag inserted into the <HEAD> 
section of the output page(s) as follows :-

      	<META NAME="description" CONTENT="your description">

This tag is often used by search engines (e.g. AltaVista) as a brief
description of the contents of your page.  If omitted the first few
lines may be shown instead, which is often less satisfactory.

The presence of a DESCRIPTION pre-processor command overrides any
description specified via a [[HYPERLINK POLICY,"Document description"]] policy line.


EMBED_BLOCK
===========

Type:        	Directive
Description: 	Delimits a definition block
Applies to:	Document construction
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_EMBED_BLOCK <name>
$_$_END_PRE

where

	<name>		Name of the block to be embedded.  This
			will be a named DEFINE_BLOCK, resolved subject
			to the scoping rules.


An EMBED_BLOCK command will cause the named DEFINE_BLOCK to be output, but
without regard to the current context information, and without causing the
prevailing context information (indentation, fonts) to be changed.

See also [[POPUP INSERT_BLOCK]]


ENTITY
======

Type:        	In-line
Description: 	Displays an HTML Entity.
Applies to:	HTML generation only
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
    [[OT]]ENTITY <HTML_entity number>[[CT]]
$_$_END_PRE
 
where,

    <HTML_entity number>        Number to be placed inside &<entity>; markup
                                in HTML
 
This tag will create an html entity in the form &<name>; or &#<number>;.
Where the supplied number maps onto a known name, the name will be used with
a view to making the HTML more comprehensible, otherwise the number form
is used.

If the software recognises that the requested entity may not be supported
by those browsers deemed to match the targeted HTML version, a WARNING is 
issued.


FILENAME
========

Type:		In-line
Description:	Substitutes the name of the files being converted
Applies to:	Document construction
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      	[[OT]]FILENAME[[CT]]
$_$_END_PRE

The tag will be replaced by the name of the file being converted.  This
facilitates the construction of sentences like

      "This file was converted from *[[OT]]FILENAME[[CT]]* at *[[OT]]TIMESTAMP[[CT]]*"

which becomes

      "This file was converted from *[[FILENAME]]* at *[[TIMESTAMP]]*"

With a change introduced in version April 2000 this tag may be used
in the document title and description policies.


FO (font) tag
=============

Type:        	In-line
Description: 	Identifies a change in font
Applies to:	RTF generation only
See policy:	(none)

*New Function*

Syntax:

$_$_BEGIN_PRE
	FO [<font_id>],[<font_size>],[<font_weight>]
$_$_END_PRE

where

$_$_BEGIN_TABLE
$_$_TABLE_LAYOUT 2,24,132
	<font_id>	Identifies the font to be used.  This must match the 
			name of a font in the SDF file.  If no name is given then
			the prevailing font will be used.
			
	<font_size>	The font size in pts.  Only needed if the default
			value in the font table is to be overridden.  
			
			The size can be supplied as an absolute value or - if a plus or
			minus sign is present - as a relative size.  So for example
			"4" means 4pt, whereas "+4" means 4pt larger than the 
			surrounding text.
			
			A value of "-" will be taken as a reset to the prevailing
			default font size.
			
	<font_weight>	The font weight.  Only needed if the default value
			in the font table is to be overridden.  Possible values
			are
			
				it (Italic)
				bo (Bold)
				bi (Bold Italic)
				no (Normal)
				- (Reset)
				
			The "reset" will cause the weight to be reset to the
			prevailing default,  i.e. no longer override the 
			prevailing font.
$_$_END_TABLE

NOTE:  The FO tag is only currently supported in RTF generation.

This in-line tag allows the font used in a document to be changed, either
locally within some text, or from this point onwards.

The FO tag should be used in conjunction with an external *Style Definition File*
which is used to define font characteristics that the FO tag can reference
by name.

Example:

$_$_BEGIN_PRE
	"This text is [[ot]]fo ,+6,bo[[ct]]big and bold,[[ot]]fo ,-,-[[ct]] but this text is
	normal again"
$_$_END_PRE

becomes

	"This text is [[fo ,+6,bo]]big and bold,[[fo ,-,-]] but this text is
	normal again"
	
(this may only work in the RTF version of this document)


FONT
====

Type:        	In-line
Description: 	Signals a change in font, font attributes
Applies to:	Text generation.  Mostly HTML.
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
        [[OT]]FONT <flag>,<name>,<size>[[CT]]
$_$_END_PRE

where,

$_$_BEGIN_TABLE
    <flag>	  Indicates whether this is a "physical" or "logical" font.
      	 	  "Physical" in this content means an actual font name such
      		  as "times", "Logical" will refer to a CSS Class name

      			0 = physical
      			1 = logical

    <name>	  Either the font name (physical markup) or the CSS class
      		  name (logical markup).  

    <size>	  The font size in points.  The default size will be 10pt.
$_$_END_TABLE


FRACTION
========

Type:        	In-line
Description: 	Implements a fraction
Applies to:	Text generation
See policy:	(none)

Syntax:	    

$_$_BEGIN_PRE
	[[OT]]FRACTION <expression>[[CT]]
$_$_END_PRE

where

$_$_BEGIN_TABLE
      <expression>	This is the fraction expression which should contain
			a slash ("/") separating the numerator and denominator

			Both values must be present.
$_$_END_TABLE


GOTO
====

Type:		In-line
Description:	Adds a hyperlink to the named section heading.
Applies to:	Hyperlink generation.  HTML and RTF implementations differ
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      	[[OT]]GOTO <Heading_name>[[CT]]
$_$_END_PRE

where

      	<Heading_name>		Name of a heading else where in the file.
      				The text used must match exactly for this tag
      				to work (case insensitive though)


Creates a hyperlink to the named section heading.  The heading must match 
the text exactly, and be in the same file.  It must also have been recognised
by the software as a heading.

For more ambitious hyperlinks, check out the [[POPUP HYPERLINK]] tag. This 
tag is a simplified version of the TOC variant of the HYPERLINK tag.

See also [[POPUP POPUP]].


HTML
====

Type:        	In-line 
Description: 	Allows raw HTML to be embedded in the end-user text
Applies to:	HTML generation only
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      [[OT]]HTML <HTML_text>[[CT]]
$_$_END_PRE

where

$_$_BEGIN_TABLE
      <HTML_Text>	Rest of line is the raw HTML to be placed in the
      			output stream at this point.
$_$_END_TABLE

This new in-line tag will allow any additional HTML markup to be passed 
directly to the output (e.g. <BLINK>).  Use of this tag should be limited
solely to HTML effects that cannot be achieved through other tags as such 
markup will be meaningless in any future RTF context.


HTML_COMMENT
============

Type:        	In-line 
Description: 	Allows HTML comments to be embedded in the end-user text
Applies to:	HTML generation only
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      [[OT]]HTML_COMMENT <comment>[[CT]]
$_$_END_PRE

where

$_$_BEGIN_TABLE
      <comment>		Rest of line is the comment to be placed inside HTML
			comment delimiters <!-- -->.  By convention this
	  		shouldn't contain two dashes "--" anywhere.
$_$_END_TABLE

This tag will allow HTML comments  to be placed in the output.  This effect
can also be achieved using the [[POPUP HTML]] tag, but that method is more
liable to error.

Use of this tag should be limited HTML as such 
markup will be meaningless in any future RTF context.


HTML_LINE
=========

Type:		Directive
Description:	Allows a single line of HTML to be embedded in the source file
Applies to:	HTML generation only
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_HTML_LINE <raw HTML commands on the rest of the line>
$_$_END_PRE

This directive allows you to embed a single line of HTML in your source
file.  The rest of the line is copied across faithfully to the output
file.

Essentially this offers the functionality as the [[POPUP BEGIN/END_HTML]] section commands
but in a more compact form.


HYPERLINK
=========

Type:        	In-line
Description: 	Defines a hyperlink to a  LINKPOINT, TOC entry or external URL
Applies to:	Hyperlink generation.  HTML and RTF implementations differ
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      [[OT]]HYPERLINK <type>,"<link_name>","<display_text>"[[CT]]
$_$_END_PRE

where,

$_$_BEGIN_TABLE
      <type>		Type of link.  Choices are:-

      				TOC	- link to a TOC entry
      				LINK 	- link to a LINKPOINT entry
      				URL	- link to a named URL

      <link_name>	Name of link.  For TOC and LINK this must be the name
      			used in the matching TOC or LINK tag.  For a URL this
      			will be the URL to link to.

      			TOC and LINK hyperlinks will be checked against the
      			list of known link points.  If no match is found an
      			error is generated, and the tag is simply replaced
      			by the display text.

      <display_text>	The on-screen text to be used for the hyperlink.  If
      			omitted it will default to the <link_name>
$_$_END_TABLE


IGNORE_THIS
===========

Type:        	In-line
Description: 	A tag whose contents are ignored.  Could be used for comments
Applies to:	Comments in the source text.
See policy:	(none)

Syntax:	    

$_$_BEGIN_PRE
      [[OT]]IGNORE_THIS <anything_you_like>[[CT]]
$_$_END_PRE

This tag is ignored.  It is replaced by a single space in the output stream.
It could be used to add a brief comment to your source that would not appear
in the output.


INCLUDE
=======

Type:		Directive
Description:	Specifies an external source file to be included at this location
Applies to:	Document construction
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_INCLUDE <filespec>
$_$_END_PRE

This directive allows you to specify the name of a source file to be
included at this point.  This is useful if you wish some standard text
inserted into many related documents, or into the same documents at
many locations.

The <filespec> must be valid for the Operating system being used, and
the location of the original source file.

The contents of the included file will be "copied into" the original
source file.  The same file may be included more than once, and included
files may contain other pre-processor commands, including more INCLUDE
statements, although there are limits on this. 

The included file will be treated as though it were part of the original
file during both the analysis and output passes.

The INCLUDE will fail if the file cannot be found, and a test for
recursive include files will be made.


INSERT_BLOCK
============

Type:        	Directive
Description: 	Invokes a definition block
Applies to:	Document construction
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_INSERT_BLOCK <name>
$_$_END_PRE

where

	<name>		Name of the block to be inserted.  This
			will be a named DEFINE_BLOCK, resolved subject
			to the scoping rules.


An INSERT_BLOCK command will cause the named DEFINE_BLOCK to be inserted
into the document source as seen as by the program.

As such the inserted block will be subject to, and able to change, the
prevailing context information (indentation, fonts etc.).

See also [[POPUP EMBED_BLOCK]]


KEYWORDS
========

Type:		Directive
Description:	Specifies keywords that help index the file's content
Applies to:	Document indexing.  HTML and RTF implementations differ
See policy:	[[HYPERLINK POLICY,"Document keywords"]]

Syntax:

$_$_BEGIN_PRE
	$_$_KEYWORDS <comma-separated list of keywords>
$_$_END_PRE

You can repeat this directive over several lines, in which case the keywords
will be concatenated.  This allows you to write multi-line keyword lists
making your source file easy to read.

In RTF the keywords form part of the document properties.

In HTML the keywords are added to a META tag inserted into the <HEAD> 
section of the output page(s) as follows :-

      	<META NAME="keywords" CONTENT="your list or keywords">

This tag is often used by search engines when indexing your HTML page.
You should add here any relevant keywords possibly not contained in
the text itself.

The presence of a KEYWORDS pre-processor command overrides any keywords
specified via a [[HYPERLINK POLICY,"Document keywords"]] policy line.


LINERULE
========

Type:        	Directive or in-line
Description: 	Signals a horizontal rule
Applies to:	Text generation
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      $_$_LINERULE <length>,<thickness>,<leading>,<alignment>,<colour>
or
      [[OT]]LINERULE <length>,<thickness>,<leading>,<alignment>,<colour>[[CT]]
$_$_END_PRE

where

$_$_BEGIN_TABLE
      <length>		length of line in pixels/pts/percent.  To specify a
      			percentage add the percent sign (%) after the value

      <thickness>	thickness of line in pixels/pts

      <leading>		leading of line in pixels (not yet implemented)

      <alignment>	Code indicating the alignment.  Possible values are

      			L - Left aligned 
      			R - Right aligned 
      			C - Centre aligned
      			J - justified

      <colour>		Colour value.  Either an HTML colour like "AABBCC"
      			or "red" or a (R,G,B) value like "0.12,0.57,1.0".
      			A RGB value must be included in quotes.  If omitted
      			the linerule will adopt the prevailing text colour.
$_$_END_TABLE

LINKPOINT
=========

Type:        	Directive or In-line
Description: 	Marks the location of an HTML anchor point
Applies to:	Hyperlink targets.  HTML and RTF implementations differ
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
      [[OT]]LINKPOINT "<link name>"[[CT]]
$_$_END_PRE

where,

$_$_BEGIN_TABLE
      <link_Name>	This is the name by which the link will be known.
      			It is also the text that will be placed in the NAME
      			anchor point, so only valid characters should be used.
$_$_END_TABLE


META_TAG
========

Type:		Directive
Description:	Specifies a meta tag to be included in a HTML header
Applies to:	Text generation.  HTML only
See policy:	(none)

*New function*

Syntax:

$_$_BEGIN_PRE
	$_$_META_TAG "Multi-word Name" value for meta tag
or	$_$_META_TAG single_word_name value for meta tag
$_$_END_PRE

The META_TAG command describes the values used to define a <META> tag that will
be added to the HTML <HEAD> section of each page created.  Each meta tag 
consists of a name and a value.

The "Name" will be the first word on the line, or a phrase if this is in quotes.
The value will be everything else on the line.


NAVIGATION_BAR
==============

Type:		Directive
Description:	Specifies a navigation bar should be added at this location
Applies to:	Text generation.  HTML only
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_NAVIGATION_BAR
$_$_END_PRE

The NAVIGATION_BAR command inserts a navigation bar that takes to to
the next/previous and contents files.  This will only be generated when
you have selected to split your file by setting the [[HYPERLINK POLICY,"Split level"]] policy.


NB "non-breaking spaces"
========================

Type:        	in-line
Description: 	Inserts multiple non-breaking spaces into the text
Applies to:	Text generation
See policy:	(none)

Syntax:	    

$_$_BEGIN_PRE
      	[[OT]]NB <Number_of_spaces>[[CT]]
$_$_END_PRE

This tag causes the specified number of non-breaking spaces to be inserted 
into the document.  The default number is 1.  In HTML this is likely to have
an identical implementation to the [[POPUP SPACES]] tag.


NEW_ROW
=======

Type:       	Directive
Description: 	Defines the start of a new row in a user-tagged table
Applies to:	Tagged table generation inside a BEGIN/END_USER_TABLE section
See policy:	(none)

*New function*

Syntax:

$_$_BEGIN_PRE
	$_$_NEW_ROW <row_type>
$_$_END_PRE

where

$_$_BEGIN_TABLE
$_$_TABLE_MIN_COLUMN_SEPARATION 2
	<row_type>	This is the row type.  Options include 

			HEAD	This is a header row
			DATA	This is a data row
			LINE	This is a line in the table

			The type may be omitted, in which case the default
			is "DATA"
$_$_END_TABLE

The command is used inside a BEGIN/END_USER_TABLE tagged table to identify
when the text that follows is in a new row of the table.  Except when the 
NEW_ROW is of type "LINE", this command should be followed by a series of 
NEW_CELL commands and their matching cell data - normally one per column.

See also :-

- [[goto BEGIN/END_USER_TABLE]]
- [[goto COLUMN_DETAILS]]
- [[goto NEW_CELL]]


NEW_CELL
========

Type:       	Directive
Description: 	Defines the start of a new cell in a user-tagged table
Applies to:	Tagged table generation inside a BEGIN/END_USER_TABLE section
See policy:	(none)

*New function*

Syntax:
$_$_BEGIN_PRE
	$_$_NEW_CELL
$_$_END_PRE

At present the NEW_CELL command doesn't take any arguments.

The NEW_CELL command is used inside a BEGIN/END_USER_TABLE tagged table 
to identify when the text that follows is in a new cell of the table.  
The contents of the cell follow on subsequent lines until either another 
NEW_CELL, NEW_ROW or END_TABLE command is encountered.

See also :-

- [[goto BEGIN/END_USER_TABLE]]
- [[goto COLUMN_DETAILS]]
- [[goto NEW_ROW]]


PAGE
====

Type:        	Directive
Description: 	Signals a new page
Applies to:	RTF generation mostly
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      $_$_PAGE
$_$_END_PRE

This signals a page boundary.  In RTF generation a page break will be generated
at this point.  In HTML the concept of page boundaries isn't really supported,
so a horizontal rule <HR> is put out instead.


POPUP
=====

Type:		In-line
Description:	Adds a hyperlink to the named section heading.
Applies to:	Hyperlink generation.  HTML and RTF implementations differ
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      	[[OT]]POPUP <Heading_name>[[CT]]
$_$_END_PRE

This behaves in an identical manner to the [[POPUP GOTO]] tag.  The only 
difference being that when an RTF file is being created for use as a Windows
Help file, the link becomes a pop-up link, instead of a full "go to" link.


SAVE/RESTORE_CONTEXT
====================

Type:        	Directive
Description: 	Delimits a definition block
Applies to:	Document construction.  Mostly HTML
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_SAVE_CONTEXT
	$_$_RESTORE_CONTEXT
$_$_END_PRE

The SAVE_CONTEXT and RESTORE_CONTEXT are intended for use with definition
blocks.  

The SAVE_CONTEXT saves all the current context information (indentation,
font etc) so that the slate may be wiped clean ready for the output of
a new block.

The RESTORE_CONTEXT command recovers the previous SAVE_CONTEXT, allowing
a document to continue as it was before the defined block was inserted.

It's unlikely that these tags should been to be used explicitly, but they
will be used implicitly inside the implementation of the 
[[POPUP BEGIN/END_HTML]] tags.


RULESET
=======

Type:		In-Line
Description:	Identifies the "Ruleset" to be used.
Applies to:	Different default Policy values.
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_RULESET <Ruleset name>
$_$_END_PRE

For certain sets of files and customers the software has been optimised
to define sets of rules (policy values) appropriate to the type of
conversions being attempted.  This is a bit like having a built-in policy
file.


SECTION
=======

Type:		Directive
Description:	Allows sections to be delimited in support of conditional conversions
Applies to:	Document construction
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	$_$_SECTION <section_name>
$_$_END_PRE

This directive is used to divide the document up into named section
types.  Section type names can be repeated through the document, and
by default text is assumed to belong to a section called "all",
indicating that this text is always copied to the output file.

Section type names must contain no white space, but may contain underscores.

This has no effect unless the user supplies a policy file indicating
that they wish to select only certain section types for output.

For example, if the text document looks like this

$_$_BEGIN_PRE
		Some text that'll always get copied, because it is in an
      		"all" section type by default.

      	$_$_SECTION Private

      		Some text that will be copied either when the preprocessor
      		is switched off, or when the user's policy file indicates
      		that "private" section types are to be included.

      	$_$_SECTION Other

      		Likewise, this is an "other" section type.

      	$_$_SECTION Private

      		And here's some more "private" text.

      	$_$_SECTION all

      		Some text that will always get copied because it is explicitly
      		in an "all" section type.
$_$_END_PRE

Then the two section types marked "private" won't be copied into the
converted file unless the user then supplies a policy file with a policy line
of the form

      	Include document section     :   Private

If the "other" section is also wanted this should be change to

      	Include document section     :   Private, Other


Note:	Be aware that any sections omitted are also omitted from
	the analysis pass.  This may have unexpected results as
      	the program responds only to the input text that is to be
      	included in the output.


SOURCE_FILE
===========

Type:      	In-line
Description: 	Adds a hyperlink to the source file that was converted
Applies to:	Text generation
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      	[[OT]]SOURCE_FILE <hyperlink_text>[[CT]]
$_$_END_PRE

where

      	<Hyperlink_text>	Text displayed on the link.  The default
      				is "source file"


Creates a hyperlink to the original source file.  The generated link is 
a local link that assumes the source is placed in the same directory as
the HTML file.


SPACES
======

Type:        	in-line
Description: 	Inserts horizontal white space into the text
Applies to:	Text generation
See policy:	(none)

Syntax:	    

$_$_BEGIN_PRE
      	[[OT]]SPACES	<Number_of_spaces>,<Size_of_space>[[CT]]
$_$_END_PRE

where,

$_$_BEGIN_TABLE
      <number of spaces>	Size of white space in spaces.

      <Size_of_space>		Size of white spaces in pts.
$_$_END_TABLE

This tag causes a number of spaces to be inserted into the document to give
a horizontal gap.  The size of the gap can be specified in Spaces or points.

When present the size in points will take precedence.

In HTML this will probably be implemented by inserting multiple non-breaking 
spaces &nbsp;, the number being equal to the size in points divided by 5 and
rounded down.


SHORTCUT_ICON
=============

Type:		Directive
Description:	Specifies the name of an shortcut icon
Applies to:	HTML styling.  HTML only
See policy:	[[HYPERLINK POLICY,"shortcut icon URL"]]

*New function*

Syntax:

$_$_BEGIN_PRE
	$_$_SHORTCUT_ICON <URL of .ico file>
$_$_END_PRE

Note, this applies to HTML only.

This directive allows you to specify the URL of a shortcut icon, usually 
with a .ico extension.  Icon files are used by certain browsers when showing
your page.  For example IE using these icons in the favourites list.

The resulting HTML is inserted into the <HEAD> section of the output
page(s) as follows :-

      	<LINK REL="SHORTCUT_ICON" HREF="<URL>">

The presence of a SHORTCUT_ICON pre-processor command will overrides any
style sheet specified via a [[HYPERLINK POLICY,"Shortcut icon URL"]] policy
line.

The URL value should be either an absolute URL, or a relative URL for where
the HTML page will be published.


STYLE_SHEET
===========

Type:		Directive
Description:	Specifies the name of an external style sheet to be used.
Applies to:	HTML styling.  HTML only
See policy:	[[HYPERLINK POLICY,"Document style sheet"]]

Syntax:

$_$_BEGIN_PRE
	$_$_STYLE_SHEET <URL of .css file>
$_$_END_PRE

Note, this applies to HTML only.

This directive allows you to specify the URL of a style sheet file,
usually with a .css extension.  Style sheet files are a new HTML feature
that allow you specify fonts and colours to be applied to your document.

The resulting HTML is inserted into the <HEAD> section of the output
page(s) as follows :-

      	<LINK REL="STYLESHEET" HREF="<URL>" TYPE="text/css">

The presence of a STYLE_SHEET pre-processor command will overrides any
style sheet specified via a [[HYPERLINK POLICY,"Document style sheet"]] policy
line.

The URL value should be either an absolute URL, or a relative URL for where
the HTML page will be published.


SUPER and SUB
=============

Type:        	In-line
Description: 	Signals a superscript or a subscript
Applies to:	Text generation.
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      [[OT]]SUPER <superscript_text>[[CT]]
      [[OT]]SUB   <subscript_text>[[CT]]
$_$_END_PRE


TABLE_ALIGN
===========

Type:		Directive
Description:	Specifies the alignment of the table(s) concerned
Applies to:	Table generation.  HTML Only (not RTF)
See policy:	[[HYPERLINK POLICY,"Default TABLE alignment"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_ALIGN <Alignment code>
$_$_END_PRE

where,

$_$_BEGIN_TABLE
	<Alignment code>	L[eft]
				R[ight]
				C[enter]
				A[utomatic]
$_$_END_TABLE

Specifies how the table should be aligned with respect to the page.  The
default behaviour is "automatic", which usually means left-justified, but
taking into account any indentation the table has.


TABLE_BGCOLOR
=============

Type:		Directive
Description:	Sets the background colour for the table(s) concerned
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE color"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_BGCOLOR <HTML colour>
$_$_END_PRE

This tag only applies to HTML production.

This tells the program what colour to use for the background to each
cell.  Not all browsers support this.  Only valid HTML Colours may be 
specified


TABLE_BORDER
============

Type:		Directive
Description:	Specifies the border size for the table(s) concerned
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE border size"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_BORDER <integer size>
$_$_END_PRE

This tag only applies to HTML production, where is sets the default value 
for the <TABLE> BORDER attribute.  

A value of 0 means "no border".  If omitted the border size will be set 
according to the table characteristics.


TABLE_BORDERCOLOR
=================

Type:		Directive
Description:	Specifies the border colour for the table(s) concerned
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE border colour"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_BORDER_COLOUR <HTML colour value>
$_$_END_PRE

This tag only applies to HTML production, where is sets the border colour
for the table.  Not all browsers support this option.


TABLE_CAPTION
=============

Type:		Directive
Description:	Specifies the table caption for the table(s) concerned
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE caption"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_CAPTION <rest of line is the caption text>
$_$_END_PRE

This tag only applies to HTML production, where it sets the table caption.

The caption should normally only be applied to individual tables, as
applying the same caption to all tables is unlikely to may much sense.


TABLE_CELLPADDING
=================

Type:		Directive
Description:	Specifies the CELLPADDING value for the table(s) concerned
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE cell padding"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_CELLPADDING <Integer value>
$_$_END_PRE

This tag only applies to HTML production, where it sets the <TABLE>
CELLPADDING attribute value.  The CELLPADDING specifies the amount of white
space added *inside* each cell around the cell contents.


TABLE_CELLSPACING
=================

Type:		Directive
Description:	Specifies the CELLSPACING value for the table(s) concerned
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE cell spacing"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_CELLSPACING <Integer value>
$_$_END_PRE

This tag only applies to HTML production, where it sets the <TABLE>
CELLSPACING attribute value.  The CELLSPACING specifies the amount of white
space added *between* individual cells.


TABLE_CELL_ALIGN
================

Type:		Directive
Description:	Specifies the alignment to be applied to each cell in the table
Applies to:	Table generation.
See policy:	[[HYPERLINK POLICY,"Default TABLE cell alignment"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_CELL_ALIGN <Alignment code>
$_$_END_PRE

where,

$_$_BEGIN_TABLE
	<ALignment_code>	L[eft]
				R[ight]
				C[enter]
				J[ustified]
$_$_END_TABLE


Specifies the default cell-alignment to be applied to table cells.  Normally
the program will try to auto-detect a suitable cell alignment on a column
by column, cel by cell basis.

You can use this to (rather crudely) set all cells to be aligned the same
way if the results are not to your taste.


TABLE_COLO(U)R_ROWS
===================

Type:		Directive
Description:	Specifies that table rows should be coloured differently
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Colour data rows"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_COLOUR_ROWS <yes/no>	
or
	$_$_TABLE_COLOR_ROWS  <yes/no>
$_$_END_PRE

Mote, this only works in HTML production, where the presence of this
tag specifies that the odd and even rows of the table should be coloured 
differently.  

If the <yes/no> value is omitted the default value is "yes".

The actual colours can be set using [[POPUP TABLE_ODD_ROW_COLO(U)R]] and
[[POPUP TABLE_EVEN_ROW_COLO(U)R]] 


TABLE_CONVERT_XREFS
===================

Type:		Directive
Description:	Specifies that section numbers should be made into hyperlinks
Applies to:	Table generation.
See policy:	[[HYPERLINK POLICY,"Convert TABLE X-refs to links"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_CONVERT_XREFS
$_$_END_PRE

If present, indicates that any section cross-references in the table may
be converted to hyperlinks 


TABLE_EVEN_ROW_COLO(U)R
=======================

Type:		Directive
Description:	Specifies colour of even rows in a table
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE even row colour"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_EVEN_ROW_COLOUR <HTML colour value> or
	$_$_TABLE_EVEN_ROW_COLOR  <HTML colour value>
$_$_END_PRE

Applies to HTML only.  When data rows are to be coloured this specifies 
the colour of the even numbered rows.


TABLE_HEADER_COLS
=================

Type:		Directive
Description:	Specifies the number of header columns in a table
Applies to:	Table analysis
See policy:	[[HYPERLINK POLICY,"Default TABLE header cols"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_HEADER_COLS	<integer number of columns>
$_$_END_PRE

Number of "header" columns (usually just 1).  These will be marked up in bold


TABLE_HEADER_ROWS
=================

Type:		Directive
Description:	Specifies the number of header rows in a table
Applies to:	Table analysis
See policy:	[[HYPERLINK POLICY,"Default TABLE header rows"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_HEADER_COLS	<integer number of columns>
$_$_END_PRE

Number of "header" rows.  These will be marked up in bold.  If omitted the
software will attempt to detect the header by looking for an underline near
the top of the table.


TABLE_IGNORE_HEADER
===================

Type:		Directive
Description:	Specifies that a table header should be ignored during column analysis
Applies to:	Table analysis
See policy:	[[HYPERLINK POLICY,"Ignore table header during analysis"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_IGNORE_HEADER
$_$_END_PRE

This tag has no attributes.

If present, indicates that the first few lines of the table - assumed to
be the header - should be ignored when calculating the table's column
structure.

This should be enabled if the table has a particularly complex header that
may confuse the program.


TABLE_LAYOUT
============

Type:		(directive/In-line)
Description:	Specifies the column structure of a table
Applies to:	Table analysis
See policy:	[[HYPERLINK POLICY,"Default TABLE layout"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_LAYOUT <number of columns>,"<col 1 spec>","<col 2>",.....
$_$_END_PRE

where,

$_$_BEGIN_TABLE
	<Number_of_cols>	Integer number of columns

	<col_n_spec>		Specification of the nth column.  The 
				specification must be contained in quote.

				Currently the specification consists of

				- the end position of the column.

				More may be added in later versions
$_$_END_TABLE

An example would be

	$_$_TABLE_LAYOUT 3,"6","21","32"

which describes a 3-column table with column boundaries at the 6th, 21st
and 32nd character positions.

Normally this directive should be placed between the 
BEGIN_TABLE...END_TABLE directives for the table it applies to, thereby
overriding the "intelligent" analysis the program would otherwise attempt
for a plain text table.


TABLE_MAY_BE_SPARSE
===================

Type:		Directive
Description:	Specifies that a table may be expected to be largely empty.
Applies to:	Table analysis
See policy:	[[HYPERLINK POLICY,"Expect sparse tables"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_MAY_BE_SPARSE
$_$_END_PRE

This tag has no attributes.

If present, indicates that the TABLE may be sparse, that is it is expected
to have a large number of empty cells.  This can affect the table analysis.


TABLE_MIN_COLUMN_SEPARATION
===========================

Type:		Directive
Description:	Specifies the minimum gap between table columns
Applies to:	Table analysis
See policy:	[[HYPERLINK POLICY,"Minimum TABLE column separation"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_MIN_COLUMN_SEPARATION <integer number of spaces>
$_$_END_PRE

Number of spaces to be taken as a column separator when analysing the
table.


TABLE_ODD_ROW_COLO(U)R
======================

Type:		Directive
Description:	Specifies colour of odd rows in a table
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE odd row colour"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TABLE_ODD_ROW_COLOUR <HTML colour value> or
	$_$_TABLE_ODD_ROW_COLOR  <HTML colour value>
$_$_END_PRE

Applies to HTML only.  When data rows are to be coloured this specifies 
the colour of the odd numbered rows.


TABLE_WIDTH
===========

Type:		Directive
Description:	Specifies the width of an HTML table
Applies to:	Table generation.  HTML only
See policy:	[[HYPERLINK POLICY,"Default TABLE width"]]

Syntax:

$_$_BEGIN_PRE
        $_$_TABLE_WIDTH <table in pixels or percentage>
$_$_END_PRE

This tells the program what value to use for the WIDTH attribute of the 
HTML table.

The WIDTH is specified either as a number (of pixels) or as a percentage
(of screen width).  Thus "400" and "75%" are both valid values (without
the quotes)


TEXT
====

Type:		In-line
Description:	Adds text without applying any conversions to it.
Applies to:	Text generation.
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      	[[OT]]TEXT <protected_text>[[CT]]
$_$_END_PRE

where

      	<protected_text>	Text to be protected.  May contain number,
      				url or emphasis characters that shouldn't
      				be converted

Protects the supplied text from normal conversions.  e.g a software version 
number that could become a hyperlink to a section number, a url that shouldn't
be converted etc.


TIMESTAMP
=========

Type:      	In-line
Description: 	Adds a date to the output text
Applies to:	Text generation.
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
	[[OT]]TIMESTAMP[[CT]]
$_$_END_PRE

Outputs the date of conversion into the output file in the format dd-mmm-yyyy.  
No attributes as yet, but expected to have formatting options added


TITLE
=====

Type:		Directive
Description:	Specifies the document title
Applies to:	Document indexing.  HTML and RTF implementations differ
See policy:	[[HYPERLINK POLICY,"Document Title"]]

Syntax:

$_$_BEGIN_PRE
	$_$_TITLE <Rest of line is the title text>
$_$_END_PRE

In RTF this becomes the title in document properties.

in HTML this allows you to specify the <TITLE>...</TITLE> to be inserted
into the <HEAD> section of the output page.  This title will appear in
the browser's frame title whenever the page is viewed, and will be the
text shown in your browser's history.


TOC
===

Type:        	Directive 
Description: 	Marks a Table of Contents entry, and the location of the 
      		associated hyperlink
Applies to:	Hyperlink generation.  HTML only
See policy:	(none)

Syntax:      

$_$_BEGIN_PRE
      $_$_TOC <level>, <link name>, <display text>
$_$_END_PRE

where,

$_$_BEGIN_TABLE
      <level>		the level in the TOC, starting with 1 being the most
      			significant, equivalent to "chapter"

      <link name>	The (usually short) name by which this linkpoint may
      			be known.  This is the value used to create an ANCHOR
      			point, and which may be referenced in any
      			HYPERLINK tag.  

      <display text>	The text to be shown in the TOC.  This will also be 
      			used to generate an ANCHOR name, and may be used in 
      			a TOC type HYPERLINK Tag, although this is marginally
      			less portable than referencing the link name

      			If omitted, defaults to the link name, and only one
      			ANCHOR is created.

$_$_END_TABLE

The TOC directive marks a point in the file that will receive an
anchor point, and then be linked to from any generated contents lists.

This can be useful to index non-headings like key diagrams and tables.

See also the section on [[POPUP HYPERLINK]] tags.


VARIABLE
========

Type:		In-line
Description:	Adds text from the matching DEFINE_VARIABLE statement
Applies to:	Text generation
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
	[[OT]]VARIABLE <name>[[CT]]
$_$_END_PRE

The tab will be replaced by the value of the nearest matching [[POPUP DEFINE_VARIABLE]]
statement.  Over time it is expected that some variables (section 
heading, page number etc.) will be automatically "defined" by the software.


VERSION
=======

Type:      	In-line
Description: 	Adds a description of the program name/version
Applies to:	Text generation
See policy:	(none)

Syntax:

$_$_BEGIN_PRE
      	[[OT]]VERSION[[CT]]
$_$_END_PRE

Outputs the version name of the conversion into the output file.  For example
"[[VERSION]]".

$_$_SECTION MERRILL
$_$_INCLUDE tag_manual_merrill.txt
$_$_SECTION ALL