What was said was never done
Don't panic, it's not really worth your while
Hsc adds several special tags to process macros, handle conditionals, include files and lots of other things.
<* comment *>- insert comments
<$content>- insert content of container macro
<$varlist>- define entities, icon-entities, tags, styles and attribute-list shotcuts
<$define>- define new (global) attribute
<$depend>- add dependency
<$exec>- execute shell-command
<$include>- include a file
<$let>- update attribute value
<$macro>- define macro-tag
<$message>- display user message
<$stripws>- strip previous/next white space
<$export>- export data to a file
<( expression )>- insert expression
<| verbatim data |>- insert verbatim data
One of the basic concepts of every computer language is that the user should be able to add comments. The machine will ignore them, but they usually help the programmer to understand his intention when looking at his source code later.
As yet another proof of the incompetence of the HTML creators, there is no reasonable way to add comments to your source code. Early versions of HTML did not offer any possibility to do that at all. Later ones support comments comparable to sgml. But as the way sgml handles comments is so messy and weird, nearly no one knows how they are really supposed to work (including myself and - more remarkable - most developers of w3-browsers).
In general, there is no way to use sgml-comments so they will work with all browsers. Many browsers are unable to find out when a comment ends, independent of whether you did it right or wrong.
Furthermore, such comments also waste bandwidth, as usually the reader will not see them (except he views the document source). And internal notes of w3-authors are usually not interesting for the public...
It is really remarkable that they managed to fuck up such a simple and usually strait forward concept like comments; even most assembler languages are smarter with this.
Anyway, with hsc you can insert a comment like
<* This is a <* nested *> hsc-comment *>
As you can see, such comments can also be nested - yes, this is a documented behaviour.
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. So they also will not waste bandwidth.Of course, if you need the standard comments, you can still use
<!-- This is an HTML/sgml-comment -->as usual. But think twice before doing so.
<$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.
<$depend>to add an additional dependency which will be noted in the project data.
ONis no more interpreted as an URI, but as a local filename relative to the source directory.
<$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.
<$depend>, the current source will be updated if dings.dat has been modified.
<'') is not interpreted as an escape character, but converted to an entity.
</PRE>, and the whole section will be rendered as pre-formatted.
<$include FILE="hugo.mod" SOURCE PRE>
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
/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>can be used to update an attribute with a new value. It has its own syntax and expects the name of the attribute and after an equal sign the new value, for instance:
<$define hugo:string="hugo"> <* create hugo and set to "hugo" *> <$let hugo=(hugo+" ist doof.")> <* update it to "hugo ist doof." *>If you do not specify a value, the attribute will be unset (but still remains defined):
<$let hugo> <* unset hugo *>You can also use Conditional Assignments for updating:
<$let hugo?=sepp> <* if sepp has any value, copy it to hugo *>
During conversion, messages might
show up. But not only hsc creates messages, also the user is
able to do so using
<$message>. Messages created by means
of this tag will always show up as message #39, but the user
can set text and class of it.
For instance this can be useful, if he wants to perform some plausibility checks of macro arguments, or for debugging purpose (``still alive'' messages).
<$message TEXT="shit happens..." CLASS="fatal"> <$message TEXT="something's wrong" CLASS="warning">
Prevwill remove all white spaces, which have occured between the previous word and the ``
<'' of this tag,
succwill skip all blanks between the ``
>'' and the next text or visible tag.
Bothwill act like if both
succwould have been specified, and
nonehas no effect on your data.
prev <$stripws type=both> succ prev <$stripws type=prev> succ prev <$stripws type=succ> succ prev <$stripws type=none> succresults in
prevsucc prev succ prev succ prev succNote that the word ``
prev'' is succeeded by two blanks, whereas the word ``
succ'' is preceded by three spaces.
<(expression)>is used to insert data of attributes and expressions.
<$define hugo:string="hugo"> <* create hugo and set it to "hugo" *> <(hugo+" ist doof.")> <* insert text "hugo ist doof." *>
<| ... |>. Of course, this is a dirty hide-out and should be used only for special cases. Example:
<|<b>some &<> bull >> shit</b>|>This can be useful when you want to use other HTML extensions together with hsc.