File: macros.html

package info (click to toggle)
hsc 0.916-2
links: PTS
area: main
in suites: hamm, slink
size: 2,584 kB
ctags: 2,277
sloc: ansic: 17,375; makefile: 396
file content (229 lines) | stat: -rw-r--r-- 9,529 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>hsc - Features - Macros</TITLE>
<LINK REV="owns" TITLE="Thomas Aglassinger" HREF="mailto:agi@giga.or.at">
<LINK REL="Next" HREF="flag.html">
<LINK REL="Copyright" HREF="../copy.html">
<LINK REL="Previous" HREF="../features/expressions.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="../features/expressions.html"><IMG SRC="../image/prev.gif" ALT="Previous" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<A HREF="flag.html"><IMG SRC="../image/next.gif" ALT="Next" ALIGN="middle" WIDTH="70" HEIGHT="16"></A>
<HR>
<H1>Macros</H1>
Macros are a powerful feature which enables you to create shortcuts
for often used text. As you can also pass arguments to macros, it is
even possible to create templates for whole pages.
<H2>General Syntax</H2>
Macros can be defined like
<BLOCKQUOTE><CODE>&lt;$macro</CODE> <I>MacroName</I>
[ <I><A HREF="flag.html">modifiers</A></I> ]
[ <I><A HREF="attrib.html">attributes</A></I> ]
<CODE>&gt;</CODE><BR>
<BR>
<I>...macro text...</I><BR><BR>
<CODE>&lt;/$macro&gt;</CODE></BLOCKQUOTE>
Here are some examples of macro definitions:
<H2>Use As Shortcuts</H2>
You can define a macro called <CODE>Hugo-Address</CODE> that only is a
shortcut for your email-address like

<PRE>&lt;$macro Hugo-Address&gt;
hugo@some.where
&lt;/$macro&gt;
</PRE>
So every time, you insert the macro-tag <CODE>&lt;Hugo-Address&gt;</CODE> in your
hsc-source, it will be replaced by

<PRE>
hugo@some.where
</PRE>
in the html-object.
<H2><A NAME="container">Container Macros</A></H2>
<P>Container macros allow you to create a macros with a text before
and after the content. While the preceding/succeeding text is
specified with the macro declaration, the content is assigned during
the macro call.</P>
<P>To declare a macro as container, you have to specify the modifier
``<CODE>/CLOSE</CODE>''. To insert the contents, use the special tag
<CODE>&lt;$content&gt;</CODE>. Alternatively, you can access the content with
the special attribute <CODE>HSC.Content</CODE>.</P>
<P>You can use <CODE>&lt;$content&gt;</CODE> multiple times inside the same macro,
too.</P>
<P>To call a container macro, act the same as with the simple macro you
have seen in the above example. But different to before, now also
a end-tag has to show up. Everything between the corresponding start- and
end-tag will be interpreted as content.</P>
<P>You should be aware of the fact that <KBD>hsc</KBD>, when scanning for the
end-tag for the macro, does not in process other macros or
<CODE>&lt;$include&gt;</CODE>-tags, but only looks at the text. Therefor the
end-tag has to show up within the same input file as the
start-tag.</P>
<P>Ok, that was a bit much. Probably a good time for an example...</P>
<H2>Declare Your Own Logical Styles</H2>
<P>One of the most laughable stories about html is the one about
physical and logical styles: It is possible to render text in bold or
italic letters using tags like <CODE>&lt;B&gt;</CODE> or <CODE>&lt;I&gt;</CODE>, which are
known as physical styles. Furthermore, you can also use some logical
styles like <CODE>&lt;CODE&gt;</CODE> or <CODE>&lt;KBD&gt;</CODE>, which should be used to
mark sequences of code or user input. Both are usually rendered same
as the physical style <CODE>&lt;TT&gt;</CODE> (typewriter font).</P>
<P>As everyone with a brain implemented could have told from the
beginning, the number of physical styles increased with every new html
release. In the draft to (never released) html-3.0 tags appeared to
render names of authors, acronyms, persons etc. The lack behind these
concepts became that obvious that even w3c found out it sucks. And so,
probably only soon before tags like
<CODE>&lt;Tim-Berners-Lee-s-favourite-tag-to-render-his-name&gt;</CODE> made it
into the specifications, this concepts has been abandoned.</P>
<P>However, it has not been replaced by anything more useful, and
this has not changed much until today; except that many people are
waiting for a new holy cow called Style Sheets.</P>
<P>So makes sense to use container macros as substitute for logical
styles, which will do nothing but enclose the content in a physical
style. Below a macro <CODE>&lt;FILE&gt;</CODE> will be created, which can be used
to render filenames:</P>


<PRE>&lt;$macro FILE /Close&gt;&lt;I&gt;&lt;$content&gt;&lt;/I&gt;&lt;/$macro&gt;
</PRE>
Your new style can be used like all other styles:
<PRE>
  ..open the file &lt;FILE&gt;hugo.txt&lt;/FILE&gt; and..
</PRE>
In this case, filenames will be rendered <I>italic</I>:
<BLOCKQUOTE>
..open the file <I>hugo.txt</I> and..
</BLOCKQUOTE>
<P>It should be rather obvious how this one works: When calling the
macro using <CODE>&lt;FILE&gt;</CODE>hugo.txt<CODE>&lt;/FILE&gt;</CODE>, hsc will scan the
input until it reaches a <CODE>&lt;/FILE&gt;</CODE>. Anything between the
corresponding start and end tag will be used as content, in this case
``hugo.txt''.</P>
<P>Now the macro text will be interpreted: The first part is easy, a
simple <CODE>&lt;I&gt;</CODE> will be inserted. After that, a <CODE>&lt;$content&gt;</CODE>
shows up, and the content read before will be inserted. In this case,
this is a simple plain text, but of course you could also use tags or
even other (container) macros. At the end of the macro, a closing
<CODE>&lt;/I&gt;</CODE> is appended, and the macro call exits.</P>
<H2>Nesting Container Macros</H2>
<P>You should be aware that the macro content (the text specified
between the corresponding start and end macro tag) can not access
attributes which have been declared for the macro text (the text which
is assigned to the macro while declaring it using
<CODE>&lt;$macro&gt;</CODE>).</P>
For example:

<PRE>&lt;$macro sepp /close hugo:string&gt;
sepp   : hugo=&lt;(hugo)&gt;
&lt;$content&gt;
sepp   : hugo=&lt;(hugo)&gt;
&lt;/$macro&gt;

&lt;$define hugo:string="content's hugo"&gt;

&lt;sepp hugo="sepp's hugo"&gt;
content: hugo=&lt;(hugo)&gt;
&lt;/sepp&gt;
</PRE>
will result in

<PRE>

sepp   : hugo=sepp's hugo

content: hugo=content's hugo
sepp   : hugo=sepp's hugo
</PRE>
The line
<PRE>content: hugo=&lt;(hugo)&gt;</PRE>
<P>does not - as some might have expected - access the attribute
<CODE>hugo</CODE> passed to the container macro <CODE>&lt;sepp&gt;</CODE> just
before, but still reads the attribute <CODE>hugo</CODE> declared above
using <CODE>&lt;$define&gt;</CODE>.</P>
The reason for this shows up soon when you start using container
macros inside container macros: every time a <CODE>&lt;$content&gt;</CODE> shows
up while just processing a <CODE>&lt;$content&gt;</CODE>, it does not make much
sense to include the same content as just before. Instead, the parser
uses the content passed to the previous but one container macro.
For example:

<PRE>&lt;$macro hinz /close&gt;
hinz=( &lt;$content&gt; )
&lt;/$macro&gt;

&lt;$macro kunz /close&gt;
kunz=( &lt;$content&gt; )
&lt;/$macro&gt;

&lt;hinz&gt;&lt;kunz&gt;...some text...&lt;/kunz&gt;&lt;/hinz&gt;
</PRE>
will result in

<PRE>

hinz=( kunz=( ...some text... ) )
</PRE>
<H2>Macros With Attributes</H2>
Take a look at this example:

<PRE>&lt;$macro Button.Next NxtRef:uri&gt;
&lt;A HREF=(NxtRef)&gt;&lt;IMG SRC=":image/next.gif" ALT="Next"&gt;&lt;/A&gt;
&lt;/$macro&gt;
</PRE>
This defines a macro that defines a button that references to the next
page. As every page has its own next page, you can set one attribute
for this macro: <CODE>NXTREF</CODE>, which is the URI that should be
referenced as the "next" page.<P>
So an example usage of this macro would be:
<PRE>
  &lt;Button.Next NXTREF=":features/rplcent.html"&gt;
</PRE>
which will give the button seen below:<P>
<A HREF="../features/rplcent.html"><IMG SRC="../image/next.gif" ALT="Next" WIDTH="70" HEIGHT="16"></A><P>
Note that the value of <CODE>NXTREF</CODE> is passed to the
<CODE>HREF</CODE> attribute within the <CODE>&lt;A&gt;</CODE> tag when the macro
is extracted.<P>
If you wonder, what <CODE>HREF=(NxtRef)</CODE> (see above) should
mean: This sets <CODE>HREF</CODE> with the value stored in
<CODE>NxtRef</CODE>. For details, read the section about <A
HREF="../features/expressions.html">expressions</A>.
<H2>Macros Inside Macros</H2>
Currently, locale macros are not supported. If you declare a macro
inside a macro, the inner macro will be declared when the outer macro
is called. For example:

<PRE>&lt;$macro outer-sepp&gt;
  now in outer sepp

  &lt;* define inner-sepp *&gt;
  &lt;$macro inner-sepp&gt;
    now in inner sepp
  &lt;/$macro&gt;

  &lt;* use inner-sepp *&gt;
  &lt;inner-sepp&gt;
&lt;/$macro&gt;

&lt;outer-sepp&gt;
</PRE>
will result in
<PRE>
  now in outer sepp

    
        now in inner sepp
</PRE>
<P>At the moment you can call <CODE>&lt;inner-sepp&gt;</CODE> even outside of
<CODE>&lt;outer-sepp&gt;</CODE>, as it is defined globally. When calling
<CODE>&lt;outer-sepp&gt;</CODE> another time, you will receive a <A HREF="../messages.html#message.59">message #59</A>,
as this tries to redefine <CODE>&lt;inner-sepp&gt;</CODE>.</P>
Obviously this behaviour doesn't make sense, but local macros are not
supported in this release.
</BODY></HTML>