The most recent version of this document can always be found online
Type: | Directive |
Description: | Toggles on and off various analysis possibilities |
Applies to: | Analysis. |
See policy: | (none) |
New in version 5.0
Syntax:
ALLOW <comma-separated list of keywords> DISALLOW <comma-separated list of keywords>
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
Headings This enables/disables 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
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
$_$_ALLOW reset, Headings
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.
$_$_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 interpreted as either a heading or list item ...
Type: | Directive |
Description: | Specifies URL that is used to resolve relative URLs |
Applies to: | Hyperlinks. HTML only |
See policy: | "Document Base URL" |
Syntax:
$_$_BASEHREF <base URL to be used>
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 "Document base URL" policy line.
Type: | Directive |
Description: | Delimits a section of text to appear in any "de-tagged" text |
Applies to: | All (ignored) |
See policy: | (none) |
Syntax:
$_$_BEGIN_ASCII ... (text to be shown only in de-tagged ASCII) ... $_$_END_ASCII
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
$_$_CONTENTS_LIST $_$_BEGIN_ASCII ... hand-written contents list ... $_$_END_ASCII
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.
Type: | Directive |
Description: | Delimits the start and end of a code sample. |
Applies to: | Text analysis |
See policy: | "Expect code samples" |
Syntax:
$_$_BEGIN_CODE ... (lines of code) ... $_$_END_CODE
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 "Use <CODE>..</CODE> markup" to see why the former is used as default).
Type: | Directive |
Description: | Delimits a table of comma-delimited data |
Applies to: | Text analysis |
See policy: | (none) |
Syntax:
$_$_BEGIN_COMMA_DELIMITED_TABLE ... (lines of comma-delimited data) ... $_$_END_COMMA_DELIMITED_TABLE
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 "Attempt table generation" policy
Type: | Directive |
Description: | Delimits a contents list in the original source file |
Applies to: | Text analysis. Mainly HTML generation. |
See policy: | (none) |
Syntax:
$_$_BEGIN_CONTENTS ... (original contents list) ... $_$_END_CONTENTS
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.
Type: | Directive |
Description: | Delimits a table of delimited data |
Applies to: | Text analysis |
See policy: | (none) |
Syntax:
$_$_BEGIN_DELIMITED_TABLE [<delimiter>] ... (lines of delimited data) ... $_$_END_DELIMITED_TABLE
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
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 "Attempt table generation" policy
Type: | Directive |
Description: | Delimits the start and end of an ASCII diagram |
Applies to: | Text analysis |
See policy: | (none) |
Syntax:
$_$_BEGIN_DIAGRAM ... (ASCII diagram) ... $_$_END_DIAGRAM
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.
Type: | Directive |
Description: | Delimits some HTML to be copied to the output |
Applies to: | HTML generation only |
See policy: | (none) |
Syntax:
$_$_BEGIN_HTML ... (block of HTML code) ... $_$_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 HTML_LINE tag offers a more compact form.
For in-line HTML use the HTML in-line tag.
Type: | Directive |
Description: | Delimits a section of input to be ignored |
Applies to: | All (ignored) |
See policy: | (none) |
Syntax:
$_$_BEGIN_IGNORE ... (text to be ignored) ... $_$_END_IGNORE
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.
Type: | Directive |
Description: | Delimits a region of pre-formatted ASCII text |
Applies to: | Text analysis |
See policy: | "Minimum automatic <PRE> size" |
Syntax:
$_$_BEGIN_PRE ... (lines of pre-formatted ASCII text) ... $_$_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 compatibility, and have the same effect as the BEGIN/END_DIAGRAM commands
Type: | Directive |
Description: | Delimits a plain text TABLE |
Applies to: | Text analysis |
See policy: | (none) |
Syntax:
$_$_BEGIN_TABLE ... (plain text table with data all aligned) ... $_$_END_TABLE
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 documentation.
Inside this section you can add other TABLE pre-processor commands to tailor the HTML generated (see The TABLE commands).
Type: | Directive |
Description: | Delimits a user-tagged table |
Applies to: | Text analysis |
See policy: | (none) |
New in version 5.0
Syntax:
$_$_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
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_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
Here's how this table appears when converted into the current format
Substance (units) |
Year Sampled |
---|---|
Alpha emitters (pCi/L) |
1999 |
Asbestos (MFL) |
1993 |
See also:-
Type: | In-line |
Description: | Signals a forced line break |
Applies to: | HTML and RTF generation |
See policy: | (none) |
Syntax:
[[BR]]
This tag has no attributes.
Type: | Directive |
Description: | Changes one of the program's "policies" |
Applies to: | All |
See policy: | (none) |
Syntax:
$_$_CHANGE_POLICY <policy text> : <policy vale>
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.
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
$_$_CHANGE_POLICY Background Colour : red $_$_CHANGE_POLICY Ignore multiple blank lines : Yes
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 3.2.
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 in version 5.0
Syntax:
$_$_COLUMN_DETAILS <col_no>,<align>,<width>
where
<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.
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 :-
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:
$_$_CONTENTS_LIST <number_levels>,<Style>,<Range>, More to be defined
where,
<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 barThe 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
Type: | In-line tag |
Description: | Allows data to be substituted into Text Commands |
Applies to: | Text Commands |
See policy: | (none) |
Syntax:
DATA <type_of_data>
where <type_of_data> can be
VERSION Program name and version TITLE Document title AUTHOR Document Author (if known) IN_FILENAME Input filename OUT_FILENAME Output filename IN_FILESIZE Input file size OUT_FILESIZE Output file size (approximate if known) IN_FILEDATE Input file's date TIMESTAMP Current time
The DATA tag is primarily intended for use in Text Command definitions. Text commands are executed against the input text, and can be used to substitute data on input before conversion. For example the command
replace_text string "<TR>" by_string "<TR><TD>[[DATA IN_FILENAME]]</TD>"
used by Detagger would insert an extra column into each row of a table before Detagger converted that file. In this case the table was being converted to delimited data to be fed to a spreadsheet program that wanted to know the filename the data came from.
For more details read the section on "Text Commands" in your program's main documentation.
Type: | Directive |
Description: | Delimits a definition block |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
$_$_DEFINE_BLOCK <block_name>,<scope> ... Block of lines ... $_$_END_BLOCK
and
$_$_RESET_BLOCK <block_name>,<scope>
where
<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
The DEFINE_BLOCK...END_BLOCK delimits a definition block. Such blocks may be instantiated by issuing INSERT_BLOCK or 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.
Type: | Directive |
Description: | Delimits an HTML "fragment" (see Using HTML Fragments) |
Applies to: | HTML Document generation only |
See policy: | (none) |
Syntax:
$_$_BEGIN_HTML_FRAGMENT <fragment_name>,<scope> ... Fragment of HTML which may include "fragment" tags ... $_$_END_BLOCK
and
$_$_RESET_HTML_FRAGMENT <fragment_name>,<scope>
where
<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 DEFINE/END_BLOCK and RESET_BLOCK.
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 Using HTML fragments
Type: | Directive |
Description: | Defines a variable value |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
$_$_DEFINE_VARIABLE <name>,<value>,<scope>
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 VARIABLE tag is used.
Type: | Directive |
Description: | Specifies the document's description |
Applies to: | HTML and RTF generation, but differently |
See policy: | "Document description" |
Syntax:
$_$_DESCRIPTION <Description on rest of line>
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 "Document description" policy line.
Type: | Directive |
Description: | Delimits a definition block |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
$_$_EMBED_BLOCK <name>
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 INSERT_BLOCK
Type: | In-line |
Description: | Displays an HTML Entity. |
Applies to: | HTML generation only |
See policy: | (none) |
Syntax:
[[ENTITY <HTML_entity number>]]
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.
Type: | In-line |
Description: | Substitutes the name of the files being converted |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
[[FILENAME]]
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 [[FILENAME]] at [[TIMESTAMP]]"
which becomes
"This file was converted from tag_manual.txt at 14-Dec-2004"
With a change introduced in version April 2000 this tag may be used in the document title and description policies.
Type: | In-line |
Description: | Identifies a change in font |
Applies to: | RTF generation only |
See policy: | (none) |
New in version 5.0
Syntax:
FO [<font_id>],[<font_size>],[<font_weight>]
where
<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
areit (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.
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:
"This text is [[fo ,+6,bo]]big and bold,[[fo ,-,-]] but this text is normal again"
becomes
"This text is big and bold, but this text is normal again"
(this may only work in the RTF version of this document)
Type: | In-line | |
Description: | Signals a change | in font, font attributes |
Applies to: | Text generation. | Mostly HTML. |
See policy: | (none) |
Syntax:
[[FONT <flag>,<name>,<size>]]
where,
<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. |
Type: | In-line |
Description: | Implements a fraction |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
[[FRACTION <expression>]]
where
<expression> This is the fraction expression which should contain
a slash ("/") separating the numerator and denominatorBoth values must be present.
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:
[[GOTO <Heading_name>]]
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 HYPERLINK tag. This tag is a simplified version of the TOC variant of the HYPERLINK tag.
See also POPUP.
Type: | In-line |
Description: | Allows raw HTML to be embedded in the end-user text |
Applies to: | HTML generation only |
See policy: | (none) |
Syntax:
[[HTML <HTML_text>]]
where
<HTML_Text> Rest of line is the raw HTML to be placed in the
output stream at this point.
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.
Type: | In-line |
Description: | Allows HTML comments to be embedded in the end-user text |
Applies to: | HTML generation only |
See policy: | (none) |
Syntax:
[[HTML_COMMENT <comment>]]
where
<comment> Rest of line is the comment to be placed inside HTML
comment delimiters <!-- -->. By convention this
shouldn't contain two dashes "--" anywhere.
This tag will allow HTML comments to be placed in the output. This effect can also be achieved using the 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.
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:
$_$_HTML_LINE <raw HTML commands on the rest of the line>
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 BEGIN/END_HTML section commands but in a more compact form.
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:
[[HYPERLINK <type>,"<link_name>","<display_text>"]]
where,
<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>
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:
[[IGNORE_THIS <anything_you_like>]]
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.
Type: | Directive |
Description: | Specifies an external source file to be included at this location |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
$_$_INCLUDE <filespec>
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.
Type: | Directive |
Description: | Invokes a definition block |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
$_$_INSERT_BLOCK <name>
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 EMBED_BLOCK
New in version 5.0
Type: | Directive |
Description: | Invokes a HTML fragment |
Applies to: | HTML conversion only |
See policy: | (none) |
Syntax:
$_$_INSERT_FRAGMENT <name>
where
<name> | Name of the HTML Fragment to be inserted. This | ||
will be a named HTML fragment, resolved subject | |||
to the scoping rules. |
An INSERT_FRAGMENT command will cause the named HTML Fragment to be inserted into the output document.
Care should be taken in the placement of these statements so that the inserted HTML doesn't interfere with any table, list etc before or after it. For best results we recommend placing this command with a blank line before and after it if possible.
Type: | Directive | |
Description: | Specifies keywords | that help index the file's content |
Applies to: | Document indexing. | HTML and RTF implementations differ |
See policy: | "Document keywords" |
Syntax:
$_$_KEYWORDS <comma-separated list of keywords>
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 "Document keywords" policy line.
Type: | Directive or in-line |
Description: | Signals a horizontal rule |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
$_$_LINERULE <length>,<thickness>,<leading>,<alignment>,<colour> or [[LINERULE <length>,<thickness>,<leading>,<alignment>,<colour>]]
where
<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.
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:
[[LINKPOINT "<link name>"]]
where,
<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.
Type: | Directive | |
Description: | Specifies a meta | tag to be included in a HTML header |
Applies to: | Text generation. | HTML only |
See policy: | (none) |
New in version 5.0
Syntax:
$_$_META_TAG "Multi-word Name" value for meta tag or $_$_META_TAG single_word_name value for meta tag
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.
Type: | Directive |
Description: | Specifies a navigation bar should be added at this location |
Applies to: | Text generation. HTML only |
See policy: | (none) |
Syntax:
$_$_NAVIGATION_BAR
The NAVIGATION_BAR command inserts a navigation bar that takes you to the next/previous and contents files. This will only be generated when you have selected to split your file by setting the "Split level" policy.
Type: | in-line |
Description: | Inserts multiple non-breaking spaces into the text |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
[[NB <Number_of_spaces>]]
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 SPACES tag.
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 in version 5.0
Syntax:
$_$_NEW_ROW <row_type>
where
<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 tableThe type may be omitted, in which case the default
is "DATA"
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 :-
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 in version 5.0
Syntax:
$_$_NEW_CELL
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 :-
Type: | Directive |
Description: | Signals a new page |
Applies to: | RTF generation mostly |
See policy: | (none) |
Syntax:
$_$_PAGE
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.
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:
[[POPUP <Heading_name>]]
This behaves in an identical manner to the 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.
Type: | Directive |
Description: | Delimits a definition block |
Applies to: | Document construction. Mostly HTML |
See policy: | (none) |
Syntax:
$_$_SAVE_CONTEXT $_$_RESTORE_CONTEXT
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 BEGIN/END_HTML tags.
Type: | In-Line |
Description: | Identifies the "Ruleset" to be used. |
Applies to: | Different default Policy values. |
See policy: | (none) |
Syntax:
$_$_RULESET <Ruleset name>
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.
Type: | Directive |
Description: | Allows sections to be delimited in support of conditional conversions |
Applies to: | Document construction |
See policy: | (none) |
Syntax:
$_$_SECTION <section_name>
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
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.
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
Type: | In-line |
Description: | Adds a hyperlink to the source file that was converted |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
[[SOURCE_FILE <hyperlink_text>]]
where
<Hyperlink_text> Text displayed on the link.
is "source file"The default
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.
Type: | in-line |
Description: | Inserts horizontal white space into the text |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
[[SPACES <Number_of_spaces>,<Size_of_space>]]
where,
<number of spaces> Size of white space in spaces. <Size_of_space> Size of white spaces in pts.
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 , the number being equal to the size in points divided by 5 and rounded down.
Type: | Directive |
Description: | Specifies the name of an shortcut icon |
Applies to: | HTML styling. HTML only |
See policy: | "shortcut icon URL" |
New in version 5.0
Syntax:
$_$_SHORTCUT_ICON <URL of .ico file>
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 "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.
Type: | Directive |
Description: | Specifies the name of an external style sheet to be used. |
Applies to: | HTML styling. HTML only |
See policy: | "Document style sheet" |
Syntax:
$_$_STYLE_SHEET <URL of .css file>
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 "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.
Type: | In-line |
Description: | Signals a superscript or a subscript |
Applies to: | Text generation. |
See policy: | (none) |
Syntax:
[[SUPER <superscript_text>]] [[SUB <subscript_text>]]
Type: | Directive |
Description: | Specifies the alignment of the table(s) concerned |
Applies to: | Table generation. HTML Only (not RTF) |
See policy: | "Default TABLE alignment" |
Syntax:
$_$_TABLE_ALIGN <Alignment code>
where,
<Alignment code> L[eft]
R[ight]
C[enter]
A[utomatic]
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.
Type: | Directive |
Description: | Sets the background colour for the table(s) concerned |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE color" |
Syntax:
$_$_TABLE_BGCOLOR <HTML colour>
(Only applies to HTML generation)
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
Type: | Directive |
Description: | Specifies the border size for the table(s) concerned |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE border size" |
Syntax:
$_$_TABLE_BORDER <integer size>
(Only applies to HTML generation)
This tag 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.
Type: | Directive |
Description: | Specifies the border colour for the table(s) concerned |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE border colour" |
Syntax:
$_$_TABLE_BORDER_COLOUR <HTML colour value>
(Only applies to HTML generation)
This tag sets the border colour for the table. Not all browsers support this option.
Type: | Directive |
Description: | Specifies the table caption for the table(s) concerned |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE caption" |
Syntax:
$_$_TABLE_CAPTION <rest of line is the caption text>
(Only applies to HTML generation)
This tag 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.
Type: | Directive |
Description: | Specifies the CELLPADDING value for the table(s) concerned |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE cell padding" |
Syntax:
$_$_TABLE_CELLPADDING <Integer value>
(Only applies to HTML generation)
This tag sets the <TABLE> CELLPADDING attribute value. The CELLPADDING attribute specifies the amount of white space added inside each cell around the cell contents.
Type: | Directive |
Description: | Specifies the CELLSPACING value for the table(s) concerned |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE cell spacing" |
Syntax:
$_$_TABLE_CELLSPACING <Integer value>
(Only applies to HTML generation)
This tag sets the <TABLE> CELLSPACING attribute value. The CELLSPACING attribute specifies the amount of white space added between individual cells.
Type: | Directive |
Description: | Specifies the alignment to be applied to each cell in the table |
Applies to: | Table generation. |
See policy: | "Default TABLE cell alignment" |
Syntax:
$_$_TABLE_CELL_ALIGN <Alignment code>
where,
<ALignment_code> L[eft]
R[ight]
C[enter]
J[ustified]
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, cell 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.
Type: | Directive |
Description: | Specifies that table rows should be coloured differently |
Applies to: | Table generation. HTML only |
See policy: | "Colour data rows" |
Syntax:
$_$_TABLE_COLOUR_ROWS <yes/no> or $_$_TABLE_COLOR_ROWS <yes/no>
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 TABLE_ODD_ROW_COLO(U)R and TABLE_EVEN_ROW_COLO(U)R
Type: | Directive |
Description: | Specifies that section numbers should be made into hyperlinks |
Applies to: | Table generation. |
See policy: | "Convert TABLE X-refs to links" |
Syntax:
$_$_TABLE_CONVERT_XREFS
If present, indicates that any section cross-references in the table may be converted to hyperlinks
Type: | Directive |
Description: | Specifies colour of even rows in a table |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE even row colour" |
Syntax:
$_$_TABLE_EVEN_ROW_COLOUR <HTML colour value> or $_$_TABLE_EVEN_ROW_COLOR <HTML colour value>
Applies to HTML only. When data rows are to be coloured this specifies the colour of the even numbered rows.
Type: | Directive |
Description: | Specifies the number of header columns in a table |
Applies to: | Table analysis |
See policy: | "Default TABLE header cols" |
Syntax:
$_$_TABLE_HEADER_COLS <integer number of columns>
Number of "header" columns (usually just 1). These will be marked up in bold
Type: | Directive |
Description: | Specifies the number of header rows in a table |
Applies to: | Table analysis |
See policy: | "Default TABLE header rows" |
Syntax:
$_$_TABLE_HEADER_COLS <integer number of columns>
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.
Type: | Directive |
Description: | Specifies that a table header should be ignored during column analysis |
Applies to: | Table analysis |
See policy: | "Ignore table header during analysis" |
Syntax:
$_$_TABLE_IGNORE_HEADER
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.
Type: | (directive/In-line) |
Description: | Specifies the column structure of a table |
Applies to: | Table analysis |
See policy: | "Default TABLE layout" |
Syntax:
$_$_TABLE_LAYOUT <number of columns>,"<col 1 spec>","<col 2>",.....
where,
<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
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.
Type: | Directive |
Description: | Specifies that a table may be expected to be largely empty. |
Applies to: | Table analysis |
See policy: | "Expect sparse tables" |
Syntax:
$_$_TABLE_MAY_BE_SPARSE
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.
Type: | Directive | |
Description: | Specifies the minimum | gap between table columns |
Applies to: | Table analysis | |
See policy: | "Minimum TABLE column separation" |
Syntax:
$_$_TABLE_MIN_COLUMN_SEPARATION <integer number of spaces>
Number of spaces to be taken as a column separator when analysing the table.
Type: | Directive |
Description: | Specifies colour of odd rows in a table |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE odd row colour" |
Syntax:
$_$_TABLE_ODD_ROW_COLOUR <HTML colour value> or $_$_TABLE_ODD_ROW_COLOR <HTML colour value>
Applies to HTML only. When data rows are to be coloured this specifies the colour of the odd numbered rows.
Type: | Directive |
Description: | Specifies the width of an HTML table |
Applies to: | Table generation. HTML only |
See policy: | "Default TABLE width" |
Syntax:
$_$_TABLE_WIDTH <table in pixels or percentage>
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)
Type: | In-line |
Description: | Adds text without applying any conversions to it. |
Applies to: | Text generation. |
See policy: | (none) |
Syntax:
[[TEXT <protected_text>]]
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.
Type: | In-line |
Description: | Adds a date to the output text |
Applies to: | Text generation. |
See policy: | (none) |
Syntax:
[[TIMESTAMP]]
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
Type: | Directive |
Description: | Specifies the document title |
Applies to: | Document indexing. HTML and RTF implementations differ |
See policy: | "Document Title" |
Syntax:
$_$_TITLE <Rest of line is the title text>
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.
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:
$_$_TOC <level>, <link name>, <display text>
where,
<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 nameIf omitted, defaults to the link name, and only one
ANCHOR is created.
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 HYPERLINK tags.
Type: | In-line |
Description: | Adds text from the matching DEFINE_VARIABLE statement |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
[[VARIABLE <name>]]
The tab will be replaced by the value of the nearest matching DEFINE_VARIABLE statement. Over time it is expected that some variables (section heading, page number etc.) will be automatically "defined" by the software.
Type: | In-line |
Description: | Adds a description of the program name/version |
Applies to: | Text generation |
See policy: | (none) |
Syntax:
[[VERSION]]
Outputs the version name of the conversion into the output file. For example "AscToHTM 5.0".
Converted from
a single text file by AscToHTM © 1997-2004 John A. Fotheringham |