7.6 Defining Macro Libraries

Reference

Developer

Tutorial
1 Introduction
2 Macros
3 Typesetting
4 Example
5 Hints
6 Examples
7 Webmaking

SEARCH

Separating Macros Into An Include File

Once you start using FunnelWeb to make webs, you'll discover that you find yourself defining and using the same macros over and over. Rather than redefining them for each new web you make, you can place them all in a FunnelWeb include file, so that they can be included in the FunnelWeb file for each web you make. Suppose that we create a file called style.fwi containing the following text:

@$@<Begin page@>@(@1@)@M@{
<HTML>
<HEAD>
<TITLE>@1</TITLE>
</HEAD>
<BODY BGCOLOR=#FFFFFF TEXT=#000033>
@}

@$@<End page@>@{
</BODY>
</HTML>
@}

@$@<Dilbert@>@Z@M@{@-
<A HREF="http://www.dilbert.com/">Dilbert</A>@}
@$@<Yahoo@>@Z@M@{@-
<A HREF="http://www.yahoo.com/">Yahoo</A>@}

Once this is done, the main web file can become:

@!************************************************

@i style

@!************************************************

@O@<index.html@>@{
@<Begin page@>@(Dave's Home Page@)

<P>Welcome to my home page. Check out my
<A HREF="@<Links FILE@>">links page</A>.

@<End page@>
@}

@!************************************************

@$@<Links FILE@>@M@{links.html@}
@O@<links.html@>@{
@<Begin page@>@(Dave's Links@)

<P>Check out @<Yahoo@> and @<Dilbert@>.

@<End page@>
@}

@!************************************************

Now we're starting to see some real simplification!

Note: It's important to attach @Z to any macro you place in an include file that you think might not be called in some webs. If you don't, FunnelWeb will issue "this macro is unused" errors for the included macros you don't use.

Library Macros

Once you've created one or more macro libraries in the form of FunnelWeb include files, you might find that sometimes you want to redefine some of the macros that the include file provides. For example, suppose that we are preparing an Australian web page and that when we refer to Yahoo, we want to refer to the Australian Yahoo site. If we try to redefine the Yahoo macro:


@i style

...

@$@<Yahoo@>@Z@M@{@-
<A HREF="http://www.yahoo.com.au/">Yahoo</A>@}

then FunnelWeb will issue an error "this macro is already defined". FunnelWeb does not allow macros to be redefined because this could be dangerous in a programming context. It would be very bad if a programmer thought they was invoking one piece of text when they were really invoking another. So FunnelWeb complains.

To stop FunnelWeb complaining, you can tag with a library macro marker @L any macro in the include file that you want to be able to redefine. For example:

@$@<Dilbert@>@Z@M@L@{@-
<A HREF="http://www.dilbert.com/">Dilbert</A>@}
@$@<Yahoo@>@Z@M@L@{@-
<A HREF="http://www.yahoo.com/">Yahoo</A>@}

This allows us to redefined the Yahoo and Dilbert macros.

Modifying Default Behaviour

The library macro mechanism allows you to set up all kinds of default behaviour that can be modified in specific webs. For example, suppose that we rewrote the macro library as:

@$@<Begin page@>@(@1@)@M@{
<HTML>
<HEAD>
<TITLE>@1</TITLE>
</HEAD>
@<Body@>
@}

@$@<End page@>@{
</BODY>
</HTML>
@}

@$@<Body@>@L@{@-
<BODY BGCOLOR=#FFFFFF TEXT=#000033>@}

Once this is done, we can modify the page background and colours of any web by redefining the Body macro without having to redefine the start and end of page macros.

@!************************************************

@i style

@$@<Body@>@{@-
<BODY BGCOLOR=#000000 TEXT=#FFFFFF>@}

@!************************************************

@O@<index.html@>@{
@<Begin page@>@(Dave's Home Page@)

<P>Welcome to my home page. Check out my
<A HREF="@<Links FILE@>">links page</A>.

@<End page@>
@}

@!************************************************

@$@<Links FILE@>@M@{links.html@}
@O@<links.html@>@{
@<Begin page@>@(Dave's Links@)

<P>Check out @<Yahoo@> and @<Dilbert@>.

@<End page@>
@}

@!************************************************

Use Of Additive Macros

Additive macros can be used to insert information into the middle of macros already defined. For example, suppose you defined:

@$@<Begin page@>@(@1@)@M@{
<HTML>
<HEAD>
<TITLE>@1</TITLE>
@<Header fields@>
</HEAD>
<BODY BGCOLOR=#FFFFFF TEXT=#000033>
@}

@$@<Header fields@>+=@{@}

Once the header fields macro is in place, you can add text such as style commands or keyword tags to each of the pages of your web without having to modify the header include file. Just add a definition, such as the following, to your main FunnelWeb file:

@$@<Header fields@>+=@{
<STYLE TYPE="text/css">
<!-- A {text-decoration: none} // -->
</STYLE>
@}

Selecting Absolute Or Relative Links

Sometimes it's important to generate a web that uses relative hyperlinks, and sometimes it's important to generate a web that uses absolute hyperlinks. For example, it's important to use relative links if you want to browse a web offline, or if you want to ensure that username and password fields in the URL are not obliterated by the following of an absolute link. Absolute links are important where a web that is normally adjacent to another web (and hence usually links to it using a relative link) is separated and must be browsed offline.

A good way to organize all this is to define FunnelWeb macros for the URLs of webs in include files, but allow them to be overruled by including files. For example, an file might contain the following definitions:

@$@<Rocksoft WWW@>@Z@M@L@{http://www.rocksoft.com/@}
@$@<Ross WWW@>@Z@M@L@{http://www.ross.net/@}
@$@<Veracity WWW@>@Z@M@L@{http://www.veracity.com/@}

These symbols are useful for referring to these various webs from within these webs. However, it is convenient for each subweb to refer to other subwebs using a relative path rather than an absolute path, so when generating (say) a subweb of the Ross webspace, the Ross macro could be redefined to:

@$@<Ross WWW@>@Z@M@{../@}

This technique can be used in various forms to manage the links in the online and offline versions of webs.