What was said was never done
Don't panic, it's not really worth your while
(Blur, "Bang")

Special Tags

hsc adds several special tags to process macros, handle conditionals, include files and lots of other things.

List of special tags

<* comment *> insert comments
<$content> insert content of container macro
<$defent>, <$deficon>, <$deftag> define entities, icon-entities and tags
<$define> define a new (global) attribute
<$depend> add a dependency
<$exec> execute shell-command
<$if>, <$else>, <$elseif> conditionals
<$include> include a file
<$let> set new attribute value
<$macro> define macro-tags
<$message> display user message
<$stripws> strip previous/next white spaces
<( expression )> insert expression
<| verbatim data |> insert verbatim data

<$content> - Insert content

The tag <$content> can be only used inside a container macro and inserts the content the user specified inside the start and end tag for the macro.

<$if> - Conditionals

Conditionals are used to decide whether some part of the text should be processed or not. As there is a lot to tell about them, there exists a whole chapter dealing with conditionals.

<$depend> - Add dependencies

If your source should not only be updated if an included file has been modified, you can use the tag <$depend> to add an additional dependency which will be noted in the project data.

Possible attributes:

ON:string: URI to depend on (relative to destination directory)
FILE:bool: If this attribute is set, ON is no more interpreted as an URI, but as a local filename relative to the source directory.

Example:

    <$depend ON="work:dings.dat" FILE>
    <$exec COMMAND="convdings FROM work:dings.dat" INCLUDE TEMPORARY>

In this example, dings.dat contains some data maintained by an external application. A script called convdings converts dings.dat to legal html data end send them to stdout, which are inserted into the current document.

Obviously, dings.dat is not maintained or included by hsc, so the current document does not depend on it. But by specifying the above <$depend>, the current source will be updated if dings.dat has been modified.

<$include> - Include file

Text files can be included using <$include>.

Possible attributes:

FILE:string/required: This specifies the input file to be included
SOURCE:bool: by default, include files are interpreted as normal *.hsc files. Therefor, they may defines macros or contain html tags to render the text. But it you for example want to include an exerpt of a source code, it is handy if a less-than character (``<'') is not interpreted as an escape character, but converted to an entity.
This attribute enables such a conversion for less than, greater than and ampersand (``&'').
PRE:bool: The included data will be enclosed inside a <PRE> ... </PRE>, and the whole section will be rendered as pre-formatted.
TEMPORARY:bool: Normally, hsc keeps track of all files included and stores the names in the project file. Later, they can be used by hscdepp to find out dependencies.
But if a file that is to be removed after the conversion ends up in the dependency list of your Makefile, it can cause trouble for make. If the attribute is enabled, the input file will not be added to the dependency list.
You should consider to enable this attribute, if invoking make returns something like
make: *** No rule to make target `hsc0x395bf7e0001.tmp', needed by `/html/hugo.html'.

Example:

<$include FILE="macro.hsc">: This can be used to include some macro definitions
<$include FILE="hugo.c" SOURCE PRE>: This is reasonable to include a source code that has been written using some programming language like Pascal, Oberon or E.

<$define> - Define attributes

You can create an attribute and pass a value to it via

<$define attribute>

If you define an attribute using <$define> inside a macro, it is of local existence only and is removed after processing the macro. You can suppress this with the attribute modifier /GLOBAL: in this case, the attribute exists until the end of conversion.

You can use the modifier /CONST to make the attribute read-only. That means it can not be updated with <$let>.

For an example, see <$let>.

<$let> - Set new attribute value

You can update an attribute's value with

<$let attribute_name = new_value>

Example:

    <$define hugo:string="hugo">       <* create hugo and set to "hugo" *>
    <$let hugo=(hugo+" ist doof.")>    <* update it to "hugo ist doof." *>

<$macro> - Macros

Macros can used to define your own short-cuts and templates. As there is a lot to tell about this feature, there exists a whole chapter dealing with macros.

<$message> - User messages

During conversion, messages might show up. But not only hsc creates messages, also the user is able to so using <$message>. For instance, when he wants to perform some plausibility checks of macro arguments.

Possible attributes:

TEXT:string/required: Specifies message text
CLASS:enum("note|warning|error|fatal")='note': Specifies message class

Example:

    <$message TEXT="shit happens..." CLASS="fatal">
    <$message TEXT="something's wrong" CLASS="warning">

<$stripws> - Strip white spaces

Possible attributes:

TYPE:enum("both|prev|succ|none")="both": This determines, which white spaces fromout the current location should be removed.
Prev will remove all white spaces, which have occured after the previous word and the ``<'' of this tag, succ will skip all blanks after the ``>'' and until the next text or visible tag.
Both will act like if both prev and succ would have been specified, and none has no effect on your data.

Example:

    prev  <$stripws type=both>   succ
    prev  <$stripws type=prev>   succ
    prev  <$stripws type=succ>   succ
    prev  <$stripws type=none>   succ

results in

    prevsucc
    prev   succ
    prev  succ
    prev     succ

Note that the word ``prev'' is succeeded by two blanks, whereas the word ``succ'' is preceded by three spaces.

<( ... )> - Insert expression

The tag <(expression)> is used to insert data of attributes and expressions.
Example:

    <$define hugo:string="hugo">       <* create hugo and set it to "hugo" *>
    <(hugo+" ist doof.")>              <* insert text "hugo ist doof." *>

<| ... |> - Insert verbatim data

If you created some perverted HTML source or use features hsc can't handle (which is theoretically impossible), you can keep hsc from parsing this section by surrounding it with <| ... |>. Of course, this is a dirty hide-out and should be used only for special cases. Example:

<|<B>some &<> bull >> shit</B>|>

The disadvantage is obvious: It is impossible to use constructs like macros or expressions inside a verbatim data section.