PreHTML Guide

Introduction

PreHTML tags are usually removed by PreHTML as it processes them. However, in some cases when an error occurs with a PreHTML tag it is left in the document. The reason why such tags are left in is so that the errors can be detected; they should not be left in a finished HTML document. If a given PreHTML tag can be left in the resulting HTML document then it is mentioned in the tag's description below, along with the circumstances under which the tag will be left in the document.

PreHTML Tags

<omit> ... </omit>

omits whatever is between the tags from the HTML document. These tags nest.

<include ...>

inserts the contents of the specified file into the HTML document.

<define ...>

defines the value of a variable (for use in later subvar tags).

<subvar ...>

substitutes a value based on the specified variable into the HTML document.

The Omit Tag

Format:

<omit> ... </omit>

Attributes:

none.

Example:

<omit>this will not be in the document</omit>

Omit tags nest, so a pair of omit tags can occur between another pair of omit tags without the inner pair's ending tag causing a premature end to the part of the document to be omitted. For example, in the following all but the last line would be omitted:

   <omit>
      Line 1 will be omitted
      <omit>
         Line 2 will be omitted
      </omit>
      Line 3 will be omitted
   <omit>
   Line 4 will not be omitted

The Include Tag

Format:

<include ...>

Attributes:

src="filename"

include the contents of the file named filename.

Example:

<include src="menubar.htsrc">

The Define Tag

Format:

<define ...>

Attributes:

var="varname"

varname is the name of the variable being defined.

type="typevalue"

the type of the variable being defined. See below for the valid types.

value="string"

the value of the variable being defined.

Examples:

<define var="title" type=string value="The Good News and the Bad News">

<define var="cover" type=file value="goodnews.jpg">

The value of the variable defined in a define tag is specified using the value attribute, and its type is specified using the type attribute. The two valid types are "string", which indicates that the variable's value is a string of text; and "file", which indicates that the variable's value is the name of a file. A variable's type is only used when it appears in a subvar tag with substitution type "contents" (see the description of the subvar tag for more information).

If no value attribute is specified or its value is unspecified then the variable's value is the empty string (""). If no type attribute is specified or its value is invalid or unspecified then the variable's type is "string". If no var attribute is specified, or if its value is not a valid variable name, then no variable is defined and the define tag is left in the document. A variable name is valid as long as it isn't the empty string. If a define tag contains more than one value attribute then only the first (i.e. leftmost) will be used and the rest will be ignored. Similarly, if a define tag contains more than one type attribute then only the first (i.e. the leftmost) will be used and the rest will be ignored.

The SubVar Tag

Format:

<subvar ...>

Attributes:

type="sub-type"

indicates the type of substitution to do. See below for the list of types

var="varname"

base the replacement value on the defined value of the variable named varname.

Examples:

<subvar type=value var="title">

<subvar type=value var="cover">

<subvar type=contents var="title">

<subvar type=contents var="cover">

<subvar type=link var="lyrics">all of the lyrics</a>

<subvar type=image var="cover" width=150 height=100>

• contents: this is the default substitution type. The replacement value depends on the variable's type, which was specified by the type attribute of the define tag that defined the variable (see the description of the define tag for more information). If the variable's type is "string" then the subvar tag is replaced with the variable's value, a text string. If the variable's type is "file" then the subvar tag is replaced with the contents of the file named by the variable's value. If the file cannot be found, opened or read then the subvar tag is left in the document. This is the only type of substitution whose result depends on the variable's type.
• value: the subvar tag is replaced with the variable's value (the value of the value attribute of the define tag that defined the variable).
• link: the subvar tag is replaced with a hyperlink tag (<a href=...>) that links to the URL given by the variable's value (the value of the value attribute of the the define tag that defined the variable). Note that the hyperlink text and the closing anchor tag (</a>) are not part of the replacement value - they must be provided separately. Any other attributes to the subvar tag will be used as attributes of the hyperlink tag.
• image: the subvar tag is replaced with an image tag (<img ...>) that uses as its SRC the image URL given by the variable's value (the value of the value attribute of the the define tag that defined the variable). Any other attributes to the subvar tag will be used as attributes of the image tag.

If more than one type attribute is present in the same subvar tag then only the first (i.e. leftmost) is used and the others are either ignored or (in the case of image and link type subvar tags) used in constructing the replacement value. If no type attribute is specified or if it has no value, then it defaults to 'contents'. If no var attribute is specified or if it hasn't been defined then the subvar tag is left in the document.