Documentation for the AscToHTM Text to HTML converter

Back to Contents List

Using the pre-processor

The pre-processor allows authors to add special lines to the source document to customise the conversion. This is usually used where someone intends regularly generating HTML from a master text document.

The Pre-processor is described more fully in the separate document the Tag manual.

The pre-processor works by giving the software hints and instructions on how to process the text. During the analysis process the software reads the source files line-by-line. The pre-processor recognises special keywords in two ways

• Directives are placed on a line by themselves. They usually instruct the software to do something, but don't usually appear directly in the output themselves. Often directives occur in pairs, marking up a section of text between them as having a special significance (e.g. to say it's a comma-delimited table)
  
  
• In-line tags can be placed anywhere in a line of input text. Usually they are substituted by some special text. For example a GOTO tag becomes a hyperlink to a section elsewhere, while a BR tag forces a line break at that point.

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

Contents of this section

Pre-processor Directives
Pre-processor In-line tags

Document commands

Pre-processor command: DESCRIPTION
Pre-processor command: KEYWORDS
Pre-processor command: TITLE
Pre-processor command: STYLE_SHEET

Section delimiters

Pre-processor command: ALLOW and DISALLOW
Pre-processor command: ASCII
Pre-processor command: CONTENTS
Pre-processor command: CODE
Pre-processor command: COMMA_DELIMITED_TABLE
Pre-processor command: DEFINE_HTML_FRAGMENT
Pre-processor command: DELIMITED_TABLE
Pre-processor command: DIAGRAM
Pre-processor command: HTML
Pre-processor command: HTML_LINE
Pre-processor command: IGNORE
Pre-processor command: PRE
Pre-processor command: TABLE
Pre-processor command: RESET_HTML_FRAGMENT
Pre-processor command: SECTION

Text definition block commands

Pre-processor command: DEFINE_BLOCK
Pre-processor command: DEFINE_VARIABLE
Pre-processor command: EMBED_BLOCK
Pre-processor command: INSERT_BLOCK
Pre-processor command: SAVE/RESTORE_CONTEXT
Pre-processor command: RESET_BLOCK
Pre-processor command: VARIABLE

Tagged Table commands

Tagged table command: BEGIN_USER_TABLE
Tagged table command: COLUMN_DETAILS
Tagged table command: NEW_ROW
Tagged table command: NEW_CELL
Tagged table: Cell contents

Table modifier commands

Pre-processor command: TABLE_ALIGN
Pre-processor command: TABLE_BORDER
Pre-processor command: TABLE_BGCOLOR
Pre-processor command: TABLE_BORDERCOLOR
Pre-processor command: TABLE_CAPTION
Pre-processor command: TABLE_CELL_ALIGN
Pre-processor command: TABLE_CELLPADDING
Pre-processor command: TABLE_CELLSPACING
Pre-processor command: TABLE_CONVERT_XREFS
Pre-processor command: TABLE_HEADER_COLS
Pre-processor command: TABLE_HEADER_ROWS
Pre-processor command: TABLE_IGNORE_HEADER
Pre-processor command: TABLE_LAYOUT
Pre-processor command: TABLE_MAY_BE_SPARSE
Pre-processor command: TABLE_MIN_COLUMN_SEPARATION
Pre-processor command: TABLE_WIDTH
Pre-processor command: TABLE_COLO(U)R_ROWS
Pre-processor command: TABLE_ODD_ROW_COLO(U)R
Pre-processor command: TABLE_EVEN_ROW_COLO(U)R

Other commands

Pre-processor command: BR
Pre-processor command: CHANGE_POLICY
Pre-processor command: CONTENTS_LIST
Pre-processor command: FILENAME
Pre-processor command: FRACTION
Pre-processor command: GOTO
Pre-processor command: HYPERLINK
Pre-processor command: IGNORE_THIS
Pre-processor command: INCLUDE
Pre-processor command: LINERULE
Pre-processor command: LINKPOINT
Pre-processor command: NAVIGATION_BAR
Pre-processor command: PAGE
Pre-processor command: POPUP
Pre-processor command: SUPER and SUB
Pre-processor command: TOC
Pre-processor command: VERSION

Pre-processor Directives

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

NOTE:

The "$_$_" must be at the start of the line, otherwise it will be ignored.

Often directives come in pairs, for example

        $_$_BEGIN_COMMA_DELIMITED_TABLE
        Date, column 2, column 3, value in column 4, column 5
        ----,-------,--------,-------,------
        Monday,  2, 3,4,5.5
        Tuesday, 2, 3.3, 4.4, 5.5
        ...
        $_$_END_COMMA_DELIMITED_TABLE

allows the comma-separated data to be transformed into the following table

Pre-processor In-line tags

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

Useful in-line tags include

• GOTO
• BR
• FRACTION
• SUPER and SUB
  
  
  

Document commands

These commands are used to control tags placed in the <HEAD..</HEAD> section of the created HTML page(s).

Not yet implemented in this release.

Pre-processor command: DESCRIPTION

You can specify a description of your page to be added as a <META> tag to the <HEAD> portion of your page by adding a line of the form

        $_$_DESCRIPTION <rest of line is used as a description>

This takes precedence over any description added via a policy file, or on the Added HTML options page.

See the discussion in the Document Description section

Pre-processor command: KEYWORDS

You can specify keywords that describe the contents of your page to be added as a <META> tag to the <HEAD> portion of your page by adding a line of the form

        $_$_KEYWORDS <rest of line is used as a list of keywords>

This takes precedence over any keywords added via a policy file, or on the Added HTML options page.

See the discussion in the Document Keywords section

Pre-processor command: TITLE

You can specify the TITLE to be added to your HTML page (in the <HEAD> section, by adding a line of the form

        $_$_TITLE <rest of line is used as a title>

This title takes precedence over any title added via a policy file, or on the Added HTML options page

Pre-processor command: STYLE_SHEET

You can specify a style sheet file to be added as a <LINK> tag to the <HEAD> portion of your page by adding a line of the form

      $_$_STYLE_SHEET <URL of your .css file>

This takes precedence over any style sheet added via a policy file, or on the CSS policies page.

Section delimiters

These commands mark the start and end of various sections in your document

Pre-processor command: ALLOW and DISALLOW

(New in version 5.0)
AscToHTM 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. This can be used, for example, to prevent a numbered list being wrongly detected as a numbered heading and vice versa.

The syntax for both commands is the same, namely

        ALLOW/DISALLOW  <comma-separated list of keywords>

Where the recognised keywords are as follows

Headings	This enables/disable the search for lines that could be treated as headings.
Lists	This enables/disables the search for lines that could be regarded as list items (either unordered bullets, or alphabetic or numeric list points)
All	Set (enable) all of the above
Reset	Reset (disable) all of the above

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

Pre-processor command: ASCII

(New in version 5.0)
The separate utility A2HDETAG is available to create a plain ASCII file, by removing all pre-processor tags from your source file. In this was a source file designed for conversion to HTML by AscToHTM can be "cleaned up" and posted as plain text elsewhere.

To support this, the BEGIN_ASCII and END_ASCII tags can be used to delimit a section of text that will only appear in the version created by A2HDETAG. This allows you to add comments to the "plain text" version, that won't appear in the HTML conversion. Use these commands as follows

        $_$_BEGIN_ASCII
        You are reading this text in a "cleaned up" version of the
        source file.  This text won't get copied across when this
        file is converted to either RTF or HTML
        $_$_END_ASCII

Pre-processor command: CONTENTS

You can mark up a section of your document as a contents list. To do this use matching BEGIN_CONTENTS and END_CONTENTS command as follows:

        $_$_BEGIN_CONTENTS
        ...
        $_$_END_CONTENTS

AscToHTM will then attempt to treat the enclosed text as a contents list.

See comments on contents list policies

Pre-processor command: CODE

You can mark up a section of your document as being a piece of sample C-like code. To do this use matching BEGIN_CODE and END_CODE command as follows:

        $_$_BEGIN_CODE
        ...
        $_$_END_CODE

AscToHTM will then mark up the enclosed text in fixed width fonts.

See comments on pre-formatted text

Pre-processor command: COMMA_DELIMITED_TABLE

(New in version 5.0)
These commands delimit a table of comma-delimited data

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)

See comments in Pre-processor command: TABLE

Pre-processor command: DEFINE_HTML_FRAGMENT

The DEFINE_HTML_FRAGMENT...END_BLOCK delimits a HTML fragment, that is a fragment of HTML that can be inserted into the output at certain key points.

It is normally recommended that all fragments defined in this manner are placed in an external HTML Fragments file, and that the Fragments file policy is used to locate this file, so that it is loaded at runtime, but you can, if you wish, embed fragment definitions in your source.

Syntax:

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

and

$_$_RESET_HTML_FRAGMENT <fragment_name>

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.

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

Pre-processor command: DELIMITED_TABLE

These directives delimit a table of delimited data

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

See comments in Pre-processor command: TABLE

Pre-processor command: DIAGRAM

You can mark up a section of your document as being a diagram or a piece of ASCII art. To do this use matching BEGIN_DIAGRAM and END_DIAGRAM commands as follows:

        $_$_BEGIN_DIAGRAM
        ...
        $_$_END_DIAGRAM

AscToHTM will then mark up the enclosed text in fixed width fonts.

See comments on pre-formatted text

Pre-processor command: HTML

You can mark up a section of your document as being pure HTML. To do this use matching BEGIN_HTML and END_HTML commands as follows:

      $_$_BEGIN_HTML
      ...
      HTML commands
      ...
      $_$_END_HTML

AscToHTM will then treat the enclosed text as pure HTML. This allows you to add images, Javascript and tables to your documents.

See also Pre-processor command: HTML_LINE

Pre-processor command: HTML_LINE

This command marks a single line in your document as being pure HTML which doesn't need converting. This achieves the same effect as the HTML section commands, but in a more compact form.

You can use this to insert images, or to manually centre some text as follows:-

        $_$_HTML_LINE   <centre>
        .
        . section of document that needs converting, and that
        . want centred.
        .
        $_$_HTML                </centre>

See also the Pre-processor command: HTML commands

Pre-processor command: IGNORE

You can mark up a section in your document that you want ignored in the output. This can be used to store change history information or whatever you want.

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.

Pre-processor command: PRE

You can mark up a section of your document as being pre-formatted text. To do this use matching BEGIN_PRE and END_PRE commands as follows:

        $_$_BEGIN_PRE
        ...
        $_$_END_PRE

AscToHTM will then mark up the enclosed text in fixed width fonts.

See comments on pre-formatted text

Pre-processor command: TABLE

You can mark up a section of your document as being a text table. To do this use matching BEGIN_TABLE and END_TABLE Commands as follows:

        $_$_BEGIN_TABLE
        ...
        $_$_END_TABLE

AscToHTM will then analyse the enclosed text to determine the table layout and will generate a proper HTML table.

General comments on marking up tables

AscToHTM has some ability to auto-detect tables (see comments on pre-formatted text), but this can be error prone. Marking up tables removes a lot of the ambiguity and so can give better results*

For tables of delimited data (as opposed to plain text tables) you should use the DELIMITED_TABLE and COMMA_DELIMITED_TABLE commands.

Note in each case the presence of these directives overrides any value set in the Attempt table generation policy, as that only refers to the auto-detection of tables. Placing markup in the source forces the text to be treated as tables.

Within each marked-up table other pre-processor commands may be used to customise the table as follows:

• TABLE_HEADER_ROWS
• TABLE_MAY_BE_SPARSE
• TABLE_MIN_COLUMN_SEPARATION

For a full list see Table modifier commands

Pre-processor command: RESET_HTML_FRAGMENT

This command is used to cancel the scope of a defined HTML Fragment. See the discussion in DEFINE_HTML_FRAGMENT

See also Using HTML fragments

Pre-processor command: SECTION

You can mark up sections of your document as being named sections. By default text belongs to a section called "all".

To do so insert SECTION command at the start of each section as follows:

        $_$_SECTION <name>
        ...

All following text will be marked as belonging to the named section until another SECTION command is encountered. AscToHTM will only copy across those sections named in the allowable sections policy, and any text in "all" sections. In this way you can generate variants of your document for different audiences (e.g. Internet and Intranet).

If you want the rest of your document to be included in all conversions, insert an "all" SECTION command as follows:

        $_$_SECTION all
        ...

Text definition block commands

These commands help with the definition and instantiation of definition blocks

Pre-processor command: DEFINE_BLOCK

The DEFINE_BLOCK...END_BLOCK delimits a Definition Block, that is a standard block of text that can be inserted into the output at certain key points - e.g. at the end of chapters. Such blocks may be instantiated by issuing Pre-processor command: INSERT_BLOCK or Pre-processor command: EMBED_BLOCK commands anywhere in the document.

It is normally recommended that text blocks defined in this manner are placed in an external HTML Fragments file, and that the Fragments file policy is used to locate this file, so that it is loaded at runtime, but you can, if you wish, embed such block definitions in your source (usually at the top of the document).

Syntax:

        $_$_DEFINE_BLOCK <block_name>,<scope>
        ...
        Block of lines
        ...
        $_$_END_BLOCK

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

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.

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

Pre-processor command: DEFINE_VARIABLE

Defines a variable value. This value may be substituted into the document text wherever a matching VARIABLE tag is used. This is particularly useful when using definition blocks, as it is a way of varying the content of the block each time it is instantiated.

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.

See Using text definition blocks

Pre-processor command: EMBED_BLOCK

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.

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.

See also INSERT_BLOCK and Using text definition blocks

Pre-processor command: INSERT_BLOCK

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

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.

See also EMBED_BLOCK and Using text definition blocks

Pre-processor command: SAVE/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 Pre-processor command: HTML section delimiters.

Syntax:

        $_$_SAVE_CONTEXT
        $_$_RESTORE_CONTEXT

Pre-processor command: RESET_BLOCK

This command is used to cancel the scope of a defined text BLOCK. See the discussion in DEFINE_BLOCK

See also Definition blocks

Pre-processor command: VARIABLE

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.

Syntax:

        [[VARIABLE <name>]]

See Using text definition blocks.

Tagged Table commands

(New in version 5.0)

In addition to converting plain text files, and sets of delimited data into tables, the software also supports a method of explicitly tagging the input as to how it should be placed in a table.

This may seem extreme, as the point of the converters is to generate the desired markup as save work, but there are a couple of situations in which this approach can be useful.

• If you are converting the source to both RTF and HTML, the same input file can be used to generate the desired output format
  
  
• If the file you are converting is being generated by some software it may be easy to add the required tags, and by so doing get the required output with minimal changes and maximum accuracy.

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

See also

• BEGIN_USER_TABLE
• COLUMN_DETAILS
• NEW_ROW
• NEW_CELL
• Table cell contents
  

Tagged table command: BEGIN_USER_TABLE

To identify a section of a source file as a user table, it must be enclosed in the BEGIN_USER_TABLE ... END_TABLE commands as follows

        $_$_BEGIN_USER_TABLE <arguments>
        ...
        <other commands to layout the table>
        ...
        $_$_END_TABLE

The command line can take arguments as follows

        $_$_BEGIN_USER_TABLE <alignment>,<margin>

where

<align>	The alignment of the table. This can be L(eft), R(ight) or C(enter)
<margin>	The margin to be applied to the table. This consists of a number and a unit. Recognised units include points ("pts" or "pt"), inches ("ins" or "in") and centimetres ("cm"). In HTML generation these margins will be approximate only

Tagged table command: COLUMN_DETAILS

After the BEGIN_USER_TABLE line will appear a number of COLUMN_DETAILS lines. These are optional, but if present they give details of the characteristics of each column in the table as follows :-

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

Tagged table command: NEW_ROW

Each new row is identifies by the present of a NEW_ROW command on a line by itself. The format is

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

except when the NEW_ROW is a "LINE", this command should be followed by a series of NEW_CELL commands and their matching cell data - normally one per column.

Tagged table command: NEW_CELL

Except for "LINE" rows, each new cell in a row identifies by the present of a NEW_CELL command on a line by itself. The contents of the cell follow on subsequent lines until either another NEW_CELL, NEW_ROW or END_TABLE command is encountered.

The format of the NEW_CELL command is

        $_$_NEW_CELL

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

Tagged table: Cell contents

Anything following a NEW_CELL command up until the next NEW_CELL, NEW_ROW or END_TABLE commands will be added into the current cell. The line structure will be preserved, so that if you have three lines of text following a NEW_CELL command, this will appear as a cell in the table with three lines of data in it.

The alignment of the cell will normally be that of the column the cell is in. This will either have been calculated automatically for the column as a whole, or will be value passed in via the matching COLUMN_DETAILS line, earlier in the table definition.

Table modifier commands

These commands can be used to tailor the appearance of a table. They're usually placed between the BEGIN_TABLE ... END_TABLE for the table they will affect, but they can also be placed at the top of the document to define defaults for all tables.

Any subsequent commands will apply for all tables detected from that point onwards. So, for example, you can change the width of each table just by issuing new TABLE_WIDTH commands.

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

Pre-processor command: TABLE_ALIGN

This policy specifies the value to be given to the ALIGN attribute of the <TABLE> tag.

Possible values are :-

Left
Right
Center

Pre-processor command: TABLE_BORDER

This policy specifies the value to be given to the BORDER attribute of the <TABLE> tag.

This attribute determines the size of the table borders. If set to 0, no border will be added to the table.

Pre-processor command: TABLE_BGCOLOR

This species the value to be used in the BGCOLOR attributes of the <TABLE> tag. Not all browsers support these attributes.

See the discussion about HTML colours

Pre-processor command: TABLE_BORDERCOLOR

This specifies the value to be used in the BORDERCOLOR attributes of the <TABLE> tag. Not all browsers support these attributes.

See the discussion about HTML colours

Pre-processor command: TABLE_CAPTION

This specifies the table caption for the table(s) concerned

Syntax:

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

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

Pre-processor command: TABLE_CELL_ALIGN

This specifies the value to be used in the ALIGN attribute of each cell within the table. By default the program will try to calculate a suitable alignment on a cell-by-cell basis. This command can override that behaviour.

Pre-processor command: TABLE_CELLPADDING

This specifies the value to be used in the CELLPADDING attribute of the <TABLE> tag.

CELLPADDING specifies the amount of white space to be added to each table cell as padding round the cell's contents.

Pre-processor command: TABLE_CELLSPACING

This specifies the value to be used in the CELLSPACING attribute of the <TABLE> tag.

CELLSPACING specifies the amount of white space to be added between cells.

Pre-processor command: TABLE_CONVERT_XREFS

Specifies that section numbers should be made into hyperlinks

Syntax:

        $_$_TABLE_CONVERT_XREFS

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

See also Convert TABLE X-refs to links

Pre-processor command: TABLE_HEADER_COLS

This specifies the number of header columns in a table

Syntax:

        $_$_TABLE_HEADER_COLS   <integer number of columns>

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

Pre-processor command: TABLE_HEADER_ROWS

This specifies how many rows in the table should be regarded as the table header.

Pre-processor command: TABLE_IGNORE_HEADER

This directive specifies that a table header should be ignored during the column 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.

This command has the same effect as the policy Ignore table header when analysing columns, but can be applied on a table-by-table basis when enclosed between TABLE command markers.

Pre-processor command: TABLE_LAYOUT

This directive allows you to specify the column structure of a table

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

Pre-processor command: TABLE_MAY_BE_SPARSE

This specifies that the table may be sparse, i.e. largely empty in places. There is no data value required on this command.

See also expect sparse tables policy

Pre-processor command: TABLE_MIN_COLUMN_SEPARATION

This specifies the minimum number of spaces to be regarded as a column separator. The default value is 1, but occasionally this gives too many columns, especially in short tables. Increasing this value will reduce the number of columns calculated.

Pre-processor command: TABLE_WIDTH

This specifies the value to be used for the WIDTH attribute of the <TABLE> tab. Table widths are specified in pixels, or as a percentage of the total screen width, thus "350" and "75%" would both be valid values.

Pre-processor command: TABLE_COLO(U)R_ROWS

This specifies the whether or not you want alternate data rows in the table coloured differently.

Both American and British spellings of "colour" are supported.

Pre-processor command: TABLE_ODD_ROW_COLO(U)R

This specifies colour for odd data rows. Only applies when row colouring is selected.

Both American and British spellings of "colour" are supported.

Pre-processor command: TABLE_EVEN_ROW_COLO(U)R

This specifies colour for even data rows. Only applies when row colouring is selected

Both American and British spellings of "colour" are supported.

Other commands

Pre-processor command: BR

This command tells the software to output a line break at this point. Usually the default is to let all lines flow together to form a paragraph. This commands can be used (e.g. in address lines to make sure lines are correctly placed on new lines).

Pre-processor command: CHANGE_POLICY

This option allows you to embed policy lines in the source document. This can be used to avoid the need for separate policy files, or to change the policy at different locations within the document (although the effects can sometimes be unpredictable).

The syntax is

        $_$_CHANGE_POLICY <policy line as in policy file>

For example placing

      $_$_CHANGE_POLICY Background colour : Red

would make all subsequent HTML files have a red background. This could be used to colour each section of a document differently when splitting a file into a number of HTML files.

For details of policy lines that can be used, see Alphabetical list of policies available in AscToHTM or the Policy manual in the HTML documentation

Pre-processor command: CONTENTS_LIST

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, but by using this command you can specify a location of your choice.

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

Pre-processor command: FILENAME

This in-line tag substitutes the name of the files being converted

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 asctohtm.txt at 14-Dec-2004"

Pre-processor command: FRACTION

This in-line tag implements a fraction

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.

So for example

The fractions [[FRACTION 5/16]] and 1[[FRACTION 1/2]].

becomes

The fractions ⁵/16 and 1¹/2.

Pre-processor command: GOTO

(New in version 5.0)
This in-line tag adds a hyperlink to the named section heading.

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)

It 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 AscToHTM as a heading.

See also the HYPERLINK and POPUP commands.

Pre-processor command: HYPERLINK

This command defines a hyperlink to a LINKPOINT, Table of Contents (TOC) entry or external URL

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>

See also GOTO and POPUP

Pre-processor command: IGNORE_THIS

This is an in-line tag whose contents are ignored. Could be used for comments

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.

See also the IGNORE command

Pre-processor command: INCLUDE

You can include one source file in another by using the include command as follows:-

        $_$_INCLUDE filename

Make sure the file is accessible from wherever AscToHTM is run, or in the same directory as the original source file. AscToHTM will read the file on each pass, treating its contents as part of the main file for both analysis and conversion purposes.

Note, the include file should be plain text, which will be converted as normal for the document. It may include other pre-processor commands including further INCLUDE commands up to a limit of 9 levels. Be careful not to set up include loops (i.e. a includes b include c includes a etc).

Include files like this can be a useful way of embedding standard disclaimers etc, and compliment the use of header and footers.

Pre-processor command: LINERULE

This command allows you to insert a separator line into your HTML output.

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.

Pre-processor command: LINKPOINT

This command marks the location of an HTML anchor point. This can then be used as the target of a hyperlink, particularly in a HYPERLINK command.

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.

Pre-processor command: 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.

Syntax:

        $_$_NAVIGATION_BAR

Pre-processor command: PAGE

(New in version 5.0)
The syntax is

      $_$_PAGE

This signals a page boundary. This command is primarily intended for use in RTF creation by AscToRTF. In HTML the concept of page boundaries isn't really supported, so a horizontal rule <HR> is put out instead.

Pre-processor command: POPUP

(New in version 5.0)
This in-line tag adds a hyperlink to the named section heading.

Syntax:

        [[POPUP <Heading_name>]]

This behaves in an identical manner to the GOTO unless you are using AscToRTF creating an RTF file for use as a Windows Help file, in which case the hyperlink link becomes a pop-up link, instead of a full "go to" link.

See also the HYPERLINK command.

Pre-processor command: SUPER and SUB

These in-line tags implement superscripts and subscripts

Syntax:

        [[SUPER <expression>]]
        [[SUB <expression>]]

So for example

        This[[SUPER superscript]] and that[[SUB subscript]]

becomes

This^superscript and that_subscript

Pre-processor command: TOC

Marks a Table of Contents entry, and the location of the associated hyperlink. 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.

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.

See also the HYPERLINK command.

Pre-processor command: VERSION

This in-line tag adds a description of the program name/version used to convert the files (e.g. "AscToHTM 5.0")

Syntax:

        [[VERSION]]

Outputs the version name of the conversion into the output file. For example "AscToHTM 5.0".

Back to Contents List

Converted from a single text file by AscToHTM © 1997-2004 John A Fotheringham