Special Tags

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

<* comment *> insert comments
<$defent> define entity
<$deficon> define icon-entity
<$deftag> define a tag
<$define> define a new (global) attribute
<$exec> execute shell commands during conversion
<$if> <$else> conditional conversion
<$include> include a file
<$insert> insert several stuff
<$let> set new attribute value
<$macro> define macro-tags
<$message> display user message
<( expression )> insert expression
<| don't parse |> don't parse section

Comments

You can insert a comment with

<* This is a hsc-comment *>

You can also nest such comments.

And you can comment out sections of html-source without any problems for the browser. This simply is possible because comments in the hsc-source are not written to the html-object.

Of course, if you need the standard comments, you can use

as usual.

Execute shell command

A shell command can be executed with

    <$exec COMMAND="command">

An example usage would be to insert a listing of a directory:

<$if (__SYSTEM__="AMIGA")>

<$exec COMMAND="list >t:hugo.list DIRS">   <* write listing to "t:hugo.list" *>
<$include FILE="t:hugo.list" SOURCE PRE>   <* include directory list *>
<$exec COMMAND="delete t:hugo.list QUIET"> <* remove temporary file *>

<$else><$if (__SYSTEM__="UNIX")>

<$exec COMMAND="ls -al >hugo.list">       <* write listing to "t:hugo.list" *>
<$include FILE="hugo.list" SOURCE PRE>    <* include directory list *>
<$exec COMMAND="rm hugo.list">            <* remove temporary file *>

<$else>

<* unknown OS: abort conversion with error message *>
<$message text="operating system not supported" class="fatal">

</$if></$if>

And the data created by this code sequence would look like this:

exmpl                        Dir ----rwed Sunday    03:40:35
features                     Dir ----rwed Today     02:49:55
image                        Dir ----rwed 31-Mar-96 02:38:13
inc                          Dir ----rwed Yesterday 23:59:13
macro                        Dir ----rwed Today     02:26:21
5 directories - 10 blocks used

If the command's return code is not equal to zero, a warning message will be displayed.

Conditional conversion

As there is a lot to tell about this feature, there exists a whole section about <$if>.

Include file

A hsc-file can be included to the text using

<$include FILE="filename" [SOURCE] [PRE]>

If you include a file this way, it is handled as an usual hsc-file. That means, all tags and special characters are handled as before.

To include a source file, eg a C- or HTML-source so that the tags are not interpreted but displayed, add the optional boolean attribute SOURCE.

<$include FILE="hugo.c" SOURCE>

Now the basic special characters "<", ">" and "&" are replaced by their entities.

Note that this does not include a <PRE>-tag to render the text as it exists with the same line breaks and spaces.

To get this done, you should use the optional boolean attribute PRE. This inserts a <PRE> before the included data and a </PRE> afterwards.

Insert several stuff

You can insert several stuff using the tag

<$insert what [options]>

Insert current date and time

You can insert the current date and time simply by

<$insert TIME>

using a default format.

Optionally, you can pass a format-string, that discribes the time. As hsc just calls the ANSI-C function strftime() to perform that task, you can use the same format specifications. Example:

<$insert TIME FORMAT="%b %d %y">

inserts current date with the strange ANSI-C __TIME__-format.

Insert text

As an required argument, you must give a string that contains the text. Example:

<$insert TEXT="hugo was here!">

inserts the text "hugo was here". Of course, this does not make much sense.<$insert TEXT="..."> is suggested to be used with attribute values. Example:

<$insert TEXT=(href)>

inserts the value of the macro-attribute href.

Define attributes

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

<$define attribute>

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

You can use the flag /CONST to make the attribute read-only. That means it can't be overwritten by <$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." *>

Define macros

As there is a lot to tell about this feature, there exists a whole section about macros...

User messages

During conversion, you can invoke messages by yourself using

    <$message TEXT="message text" [CLASS="class"]>

For an example, look at <$exec>.

Insert expression

This tag is used to insert data of attributes and expressions. For example:

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

Don't parse section

If you created some perverted HTML source or use features hsc can't handle (which is theoretically impossible), you can keep of 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.

Define an entity

This tag should be used within hsc.prefs only. It defines a new entity. The (required) attribute NAME declares the name of the entity, RPLC the character that should be replaced by this entity if found in the hsc-source and NUM is the numeric representation of this entity.

Example: <$defent NAME="uuml" RPLC="ü" NUM="252">

Define icon-entity

This tag should be used within hsc.prefs only. It defines a new icon-entity. The only (required) attribute is NAME which declares the name of the icon.

Example: <$deficon NAME="mail">

Define a tag

This tag should be used within hsc.prefs only. It defines a new tag, and is used quite similar to <$macro>, exept that a tag-definition requires no macro-text and end-tag to be followed.

Thomas Aglassinger (agi@giga.or.at), 29-May-1996