1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>hsc - Features - Special Tags</TITLE>
<LINK REV="owns" TITLE="Thomas Aglassinger" HREF="mailto:agi@giga.or.at">
<LINK REL="Next" HREF="checkuri.html">
<LINK REL="Copyright" HREF="../copy.html">
<LINK REL="Previous" HREF="../envvar.html">
<META name="ROBOTS" content="NOINDEX, NOFOLLOW">
</HEAD>
<BODY>
<A HREF="../index.html"><IMG SRC="../image/main.gif" ALT="Contents" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<IMG SRC="../image/noindex.gif" ALT="-----" ALIGN="middle" WIDTH="70" HEIGHT="16">
<A HREF="../copy.html"><IMG SRC="../image/copy.gif" ALT="Copyright" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="../index.html"><IMG SRC="../image/back.gif" ALT="Up" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="../envvar.html"><IMG SRC="../image/prev.gif" ALT="Previous" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="checkuri.html"><IMG SRC="../image/next.gif" ALT="Next" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<HR>
<P ALIGN="right"><I>What was said was never done<BR>Don't panic, it's not really worth your while</I><BR>
(Blur, "Bang")
</P>
<H1>Special Tags</H1>
<P><KBD>Hsc</KBD> adds several special tags to process macros, handle
conditionals, include files and lots of other things.</P>
<H2>List Of Special Tags</H2>
<UL>
<LI><A HREF="#comments"><CODE><* <I>comment</I> *></CODE></A> - insert comments
<LI><A HREF="#content"><CODE><$content></CODE></A>
- insert content of container macro
<LI><A HREF="prefs.html#defent"><CODE><$defent></CODE></A>,
<A HREF="prefs.html#deficon"><CODE><$deficon></CODE></A>,
<A HREF="prefs.html#deftag"><CODE><$deftag></CODE></A>
- define entities, icon-entities and tags
<LI><A HREF="#define"><CODE><$define></CODE></A> - define new (global) attribute
<LI><A HREF="#depend"><CODE><$depend></CODE></A> - add dependency
<LI><A HREF="exec.html"><CODE><$exec></CODE></A> - execute shell-command
<LI><A HREF="if.html"><CODE><$if></CODE>, <CODE><$else></CODE>, <CODE><$elseif></CODE></A> - conditionals
<LI><A HREF="#include"><CODE><$include></CODE></A> include a file
<LI><A HREF="#let"><CODE><$let></CODE></A> - update attribute value
<LI><A HREF="../macro/macros.html"><CODE><$macro></CODE></A> - define macro-tag
<LI><A HREF="#message"><CODE><$message></CODE></A> - display user message
<LI><A HREF="#stripws"><CODE><$stripws></CODE></A> - strip previous/next white space
<LI><A HREF="#expression"><CODE><( <I>expression</I> )></CODE></A> - insert expression
<LI><A HREF="#dontparse"><CODE><| <I>verbatim data</I> |></CODE></A> - insert verbatim data
</UL>
<HR>
<H2><A NAME="comments"><* ... *> - Comments</A></H2>
<P>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.</P>
<P>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).</P>
<P>In general, there is <STRONG>no</STRONG> 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.</P>
<P>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...</P>
<P>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.</P>
<P>Anyway, with <KBD>hsc</KBD> you can insert a comment like</P>
<PRE><* This is a <* nested *> hsc-comment *></PRE>
<P>As you can see, such comments can also be nested - yes, this is
a documented behaviour.<P>
<P>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.</P>
Of course, if you need the standard comments, you can still use
<PRE><!-- This is a html/sgml-comment --></PRE>
as usual. But think twice before doing so.
<HR>
<H2><A NAME="content"><$content> - Insert Content</A></H2>
The tag <CODE><$content></CODE> can be only used inside a
<A HREF="../macro/macros.html#container">container macro</A>
and inserts the content the user specified inside the start and
end tag for the macro.
<HR>
<H2><A NAME="if"><$if> - Conditionals</A></H2>
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 <A HREF="if.html">conditionals</A>.
<HR>
<H2><A NAME="depend"><$depend> - Add Dependencies</A></H2>
If your source should not only be updated if an included
file has been modified, you can use the tag <CODE><$depend></CODE> to
add an additional dependency which will be noted in the project
data.
<P><STRONG>Possible attributes:</STRONG><DL>
<DT><CODE>ON:string</CODE><DD>
URI to depend on (relative to destination directory)
<DT><CODE>FILE:bool</CODE><DD>
If this attribute is set, <CODE>ON</CODE> is no more
interpreted as an URI, but as a local filename relative
to the source directory.
</DL>
<STRONG>Example</STRONG>:
<PRE>
<$depend ON="work:dings.dat" FILE>
<$exec COMMAND="convdings FROM work:dings.dat" INCLUDE TEMPORARY>
</PRE>
<P>In this example, <I>dings.dat</I> contains some data
maintained by an external application. A script called
<KBD>convdings</KBD> converts <I>dings.dat</I> to
legal html data end send them to <CODE>stdout</CODE>, which are inserted
into the current document.</P>
Obviously, <I>dings.dat</I> is not maintained or included
by hsc, so the current document does not depend on it.
But by specifying the above <CODE><$depend></CODE>, the current
source will be updated if <I>dings.dat</I> has been
modified.
<HR>
<H2><A NAME="include"><$include> - Include File</A></H2>
Text files can be included using <CODE><$include></CODE>.
<P><STRONG>Possible attributes:</STRONG><DL>
<DT><CODE>FILE:string/required</CODE><DD>
This specifies the input file to be included
<DT><CODE>SOURCE:bool</CODE><DD>
by default, include files are interpreted as normal
<I>*.hsc</I> files. Therefor, they may defines macros
or contain html tags to render the text. But if you for
example want to include an excerpt of a source code, it is
handy if a less-than character (``<CODE><</CODE>'') is not interpreted
as an escape character, but converted to an entity.<BR>
This attribute enables such a conversion for less than, greater
than and ampersand (``<CODE>&</CODE>'').
<DT><CODE>PRE:bool</CODE><DD>
The included data will be enclosed inside a
<CODE><PRE></CODE> ... <CODE></PRE></CODE>, and the whole section will
be rendered as pre-formatted.
<DT><CODE>TEMPORARY:bool</CODE><DD>
Normally, <KBD>hsc</KBD> keeps track of all files included and stores
the names in the project file. Later, they can be used by
<KBD>hscdepp</KBD> to find out dependencies.<BR>
But if a file that is to be removed after the conversion
ends up in the dependency list of your <I>Makefile</I>, it can
cause trouble for <KBD>make</KBD>. If the attribute is enabled, the
input file will not be added to the dependency list.<BR>
You should consider to enable this attribute, if invoking
<KBD>make</KBD> returns something like<BR>
<SAMP>make: *** No rule to make target `hsc0x395bf7e0001.tmp',
needed by `/html/hugo.html'.</SAMP>
</DL>
<STRONG>Example</STRONG>:
<DL>
<DT><CODE><$include FILE="macro.hsc"></CODE>
<DD>This can be used to include some macro definitions
<DT><CODE><$include FILE="hugo.mod" SOURCE PRE></CODE>
<DD>This is reasonable to include a source code that has been
written using some programming language like Oberon, Pascal or E.
</DL>
<HR>
<H2><A NAME="define"><$define> - Define A New Attribute</A></H2>
You can create an attribute and pass a value to it via
<BLOCKQUOTE>
<CODE><$define <I><A HREF="../macro/attrib.html">attribute-declaration</A></I>></CODE>
</BLOCKQUOTE>
<P>If you define an attribute using <CODE><$define></CODE> inside a
macro, it is of local existence only and is removed after
processing the macro. You can suppress this with the attribute
modifier <CODE>/GLOBAL</CODE>: in this case, the attribute exists
until the end of conversion.</P>
<P>You can use the modifier <CODE>/CONST</CODE> to make the
attribute read-only. That means it can not be updated with
<CODE><$let></CODE>.</P>
For an example, see <CODE><$let></CODE>.
<HR>
<H2><A NAME="let"><$let> - Update The Value Of An Attribute</A></H2>
The tag <CODE><$let></CODE> 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:
<PRE>
<$define hugo:string="hugo"> <* create hugo and set to "hugo" *>
<$let hugo=(hugo+" ist doof.")> <* update it to "hugo ist doof." *>
</PRE>
If you do not specify an value, the attribute will
be unset (but still remains defined):
<PRE>
<$let hugo> <* unset hugo *>
</PRE>
You can also use <A HREF="assign.html#cond-assign">Conditional Assignments</A> for updating:
<PRE>
<$let hugo?=sepp> <* if sepp has any value, copy it to hugo *>
</PRE>
<HR>
<H2><A NAME="macro"><$macro> - Define Macro</A></H2>
Macros can be 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 <A HREF="../macro/macros.html">macros</A>.
<HR>
<H2><A NAME="message"><$message> - Launch User Message</A></H2>
<P>During conversion, messages might show up. But not only <KBD>hsc</KBD>
creates messages, also the user is able to do so using
<CODE><$message></CODE>. Messages created by means of this tag will
always show up as <A HREF="../messages.html#message.39">message #39</A>, but the user can set text and
class of it.</P>
<P>For instance this can be useful, if he wants to perform some
plausibility checks of macro arguments, or for debugging purpose
(``still alive'' messages).</P>
<P><STRONG>Possible attributes:</STRONG><DL>
<DT><CODE>TEXT:string/required</CODE><DD>
Specifies message text
<DT><CODE>CLASS:enum("note|warning|error|fatal")='note'</CODE><DD>
Specifies message class
</DL>
<STRONG>Example</STRONG>:
<PRE>
<$message TEXT="shit happens..." CLASS="fatal">
<$message TEXT="something's wrong" CLASS="warning">
</PRE>
<HR>
<H2><A NAME="stripws"><$stripws> - Strip White Space</A></H2>
<P><STRONG>Possible attributes:</STRONG><DL>
<DT><CODE>TYPE:enum("both|prev|succ|none")="both"</CODE><DD>
This specifies which white space at the current
location should be removed.<BR>
<CODE>Prev</CODE> will remove all white spaces, which have occured
between the previous word and the ``<CODE><</CODE>'' of this tag,
<CODE>succ</CODE> will skip all blanks between the ``<CODE>></CODE>''
and the next text or visible tag.<BR>
<CODE>Both</CODE> will act like if both <CODE>prev</CODE> and
<CODE>succ</CODE> would have been specified, and
<CODE>none</CODE> has no effect on your data.
</DL>
<STRONG>Example</STRONG>:
<PRE>
prev <$stripws type=both> succ
prev <$stripws type=prev> succ
prev <$stripws type=succ> succ
prev <$stripws type=none> succ
</PRE>
results in
<PRE>
prevsucc
prev succ
prev succ
prev succ
</PRE>
Note that the word ``<CODE>prev</CODE>'' is succeeded by two blanks,
whereas the word ``<CODE>succ</CODE>'' is preceded by three spaces.
<HR>
<H2><A NAME="expression"><( ... )> - Insert Expression</A></H2>
The tag <CODE><(<I>expression</I>)></CODE> is used to insert data
of attributes and
<A HREF="expressions.html">expressions</A>.<BR>
<STRONG>Example</STRONG>:
<PRE>
<$define hugo:string="hugo"> <* create hugo and set it to "hugo" *>
<(hugo+" ist doof.")> <* insert text "hugo ist doof." *>
</PRE>
<HR>
<H2><A NAME="dontparse"><| ... |> - Insert Verbatim Data</A></H2>
If you created some perverted html-code or use features <KBD>hsc</KBD>
can't handle (which is theoretically impossible), you can keep
<KBD>hsc</KBD> from parsing this section by surrounding it with <CODE><| ...
|></CODE>. Of course, this is a dirty hide-out and should be used
only for special cases.
<STRONG>Example</STRONG>:
<PRE><|<B>some &<> bull >> shit</B>|></PRE>
This can be useful when you want to use <A
HREF="../others.html">other html-extensions</A> together with <KBD>hsc</KBD>.
<BR>
</BODY></HTML>
|
