The "Tag Manual" for JafSoft's text conversion utilities

The most recent version of this document can always be found online


Previous page Back to Contents List  

5 Complete TAG list

ALLOW and DISALLOW

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
        ...


BASEHREF

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.


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_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.


BEGIN/END_CODE

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).


BEGIN/END_COMMA_DELIMITED_TABLE

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


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_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.


BEGIN/END_DELIMITED_TABLE

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


BEGIN/END_DIAGRAM

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.


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_HTML
        ...
        (block of HTML code)
        ...
        $_$_END_HTML

AscToHTM

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.


BEGIN/END_IGNORE

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.


BEGIN/END_PRE

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


BEGIN/END_TABLE

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).

BEGIN/END_USER_TABLE

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:-

BR (line break)

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.


CHANGE_POLICY

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.

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

        $_$_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 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.

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 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.

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.

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

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.


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 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 :-

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:

        $_$_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 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


DATA

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.

DEFINE/END_BLOCK and RESET_BLOCK

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.


DEFINE_HTML_FRAGMENT and RESET_HTML_FRAGMENT

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


DEFINE_VARIABLE

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.


DESCRIPTION

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.


EMBED_BLOCK

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


ENTITY

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.


FILENAME

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.


FO (font) tag

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
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.

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)


FONT

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.


FRACTION

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 denominator
  Both values must be present.


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:

        [[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.


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:

      [[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.


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:

      [[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.


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:

        $_$_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.


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:

      [[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>


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:

      [[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.


INCLUDE

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.


INSERT_BLOCK

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


INSERT_FRAGMENT

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.


KEYWORDS

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.


LINERULE

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.

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:

      [[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.


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 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.


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:

        $_$_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.


NB "non-breaking spaces"

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.


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 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 table
  The 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 :-

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 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 :-

PAGE

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.


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:

        [[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.


SAVE/RESTORE_CONTEXT

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.


RULESET

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.


SECTION

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

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:

        [[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.


SPACES

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 &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: "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.


STYLE_SHEET

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.


SUPER and SUB

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

Syntax:

      [[SUPER <superscript_text>]]
      [[SUB   <subscript_text>]]


TABLE_ALIGN

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.


TABLE_BGCOLOR

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


TABLE_BORDER

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.


TABLE_BORDERCOLOR

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.


TABLE_CAPTION

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.


TABLE_CELLPADDING

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.


TABLE_CELLSPACING

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.


TABLE_CELL_ALIGN

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.


TABLE_COLO(U)R_ROWS

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


TABLE_CONVERT_XREFS

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


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: "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.


TABLE_HEADER_COLS

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


TABLE_HEADER_ROWS

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.


TABLE_IGNORE_HEADER

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.


TABLE_LAYOUT

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.


TABLE_MAY_BE_SPARSE

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.


TABLE_MIN_COLUMN_SEPARATION

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.


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: "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.


TABLE_WIDTH

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)


TEXT

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.


TIMESTAMP

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


TITLE

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.


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:

      $_$_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 name
  If 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.


VARIABLE

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.


VERSION

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".



Previous page Back to Contents List  

Valid HTML 4.0! Converted from a single text file by AscToHTM
© 1997-2004 John A. Fotheringham
Converted by AscToHTM