File: web_libraries.html

package info (click to toggle)
funnelweb-doc 3.2d-4.2
links: PTS
area: main
in suites: forky, sid, trixie
size: 3,744 kB
sloc: perl: 241; makefile: 23
file content (384 lines) | stat: -rw-r--r-- 11,545 bytes
parent folder | download | duplicates (5)

<HTML>
<!--
***********************************************************************
FUNNELWEB MANUAL WEB PAGE
=========================
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.

Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.

***********************************************************************
-->

<HEAD>
<TITLE>7.6 Defining Macro Libraries</TITLE>
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
</HEAD>
<BODY BACKGROUND="binary/background.gif"
      BGCOLOR="#FFFFFF"
      TEXT="#000000"
      VLINK="#660000"
      LINK="#FF0000"
      ALINK="#CC0000">

<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>

<FONT SIZE="2">
<BR>

<A HREF="http://www.ross.net/"
 TARGET="rosshome"
 onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
 <IMG SRC="binary/rossnet_logo.gif"
  WIDTH="64" HEIGHT="32"
  BORDER="0" ALT="RossNet"
  HSPACE="0" VSPACE="1"></A><BR>
<BR>

<A HREF="../index.shtml"
 TARGET="funnelweb"
 onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
 <IMG SRC="binary/linklogo.gif"
  WIDTH="64" HEIGHT="32"
  BORDER="0" ALT="FunnelWeb"
  HSPACE="0" VSPACE="1"></A><BR>
<BR>
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
<A HREF="../reference/index.html"
 TARGET="funnelwebreference"
 onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
<BR>
<A HREF="../developer/index.html"
 TARGET="funnelwebdeveloper"
 onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
<BR>
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</FONT></A><BR>

<BR>
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
</FONT>
</TD></TR></TABLE>


</TD>
<TD WIDTH="360" VALIGN="top">
<FONT SIZE="3">


<A HREF="../reference/index.html"><IMG SRC="binary/title.gif"
 WIDTH="302" HEIGHT="24"
 BORDER="0" ALT="FunnelWeb Tutorial Manual"
 HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">7.6 Defining Macro Libraries</FONT><BR>


<P><BR><FONT SIZE="4"><STRONG>Separating Macros Into An Include File</STRONG></FONT><BR>

<P>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 <SAMP>style.fwi</SAMP> containing the
following text:

<P>
<PRE>
@$@&lt;Begin page@&gt;@(@1@)@M@{
&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;@1&lt;/TITLE&gt;
&lt;/HEAD&gt;
&lt;BODY BGCOLOR=#FFFFFF TEXT=#000033&gt;
@}

@$@&lt;End page@&gt;@{
&lt;/BODY&gt;
&lt;/HTML&gt;
@}

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

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

<P>
<PRE>
@!************************************************

@i style

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

@O@&lt;index.html@&gt;@{
@&lt;Begin page@&gt;@(Dave's Home Page@)

&lt;P&gt;Welcome to my home page. Check out my
&lt;A HREF="@&lt;Links FILE@&gt;"&gt;links page&lt;/A&gt;.

@&lt;End page@&gt;
@}

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

@$@&lt;Links FILE@&gt;@M@{links.html@}
@O@&lt;links.html@&gt;@{
@&lt;Begin page@&gt;@(Dave's Links@)

&lt;P&gt;Check out @&lt;Yahoo@&gt; and @&lt;Dilbert@&gt;.

@&lt;End page@&gt;
@}

@!************************************************
</PRE>

<P>Now we're starting to see some real simplification!

<P>Note: It's important to attach <SAMP>@Z</SAMP> 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.

<P><BR><FONT SIZE="4"><STRONG>Library Macros</STRONG></FONT><BR>

<P>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:

<P>
<PRE>

@i style

...

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

<P>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.

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

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

<P>This allows us to redefined the Yahoo and Dilbert macros.

<P><BR><FONT SIZE="4"><STRONG>Modifying Default Behaviour</STRONG></FONT><BR>

<P>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:

<P>
<PRE>
@$@&lt;Begin page@&gt;@(@1@)@M@{
&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;@1&lt;/TITLE&gt;
&lt;/HEAD&gt;
@&lt;Body@&gt;
@}

@$@&lt;End page@&gt;@{
&lt;/BODY&gt;
&lt;/HTML&gt;
@}

@$@&lt;Body@&gt;@L@{@-
&lt;BODY BGCOLOR=#FFFFFF TEXT=#000033&gt;@}
</PRE>

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

<P>
<PRE>
@!************************************************

@i style

@$@&lt;Body@&gt;@{@-
&lt;BODY BGCOLOR=#000000 TEXT=#FFFFFF&gt;@}

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

@O@&lt;index.html@&gt;@{
@&lt;Begin page@&gt;@(Dave's Home Page@)

&lt;P&gt;Welcome to my home page. Check out my
&lt;A HREF="@&lt;Links FILE@&gt;"&gt;links page&lt;/A&gt;.

@&lt;End page@&gt;
@}

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

@$@&lt;Links FILE@&gt;@M@{links.html@}
@O@&lt;links.html@&gt;@{
@&lt;Begin page@&gt;@(Dave's Links@)

&lt;P&gt;Check out @&lt;Yahoo@&gt; and @&lt;Dilbert@&gt;.

@&lt;End page@&gt;
@}

@!************************************************
</PRE>

<P><BR><FONT SIZE="4"><STRONG>Use Of Additive Macros</STRONG></FONT><BR>

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

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

@$@&lt;Header fields@&gt;+=@{@}
</PRE>

<P>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:

<P>
<PRE>
@$@&lt;Header fields@&gt;+=@{
&lt;STYLE TYPE="text/css"&gt;
&lt;!-- A {text-decoration: none} // --&gt;
&lt;/STYLE&gt;
@}
</PRE>

<P><BR><FONT SIZE="4"><STRONG>Selecting Absolute Or Relative Links</STRONG></FONT><BR>

<P>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.

<P>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:

<P>
<PRE>
@$@&lt;Rocksoft WWW@&gt;@Z@M@L@{http://www.rocksoft.com/@}
@$@&lt;Ross WWW@&gt;@Z@M@L@{http://www.ross.net/@}
@$@&lt;Veracity WWW@&gt;@Z@M@L@{http://www.veracity.com/@}
</PRE>

<P>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:

<P>
<PRE>
@$@&lt;Ross WWW@&gt;@Z@M@{../@}
</PRE>

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


<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"   VALIGN="bottom"><A HREF="web_style.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
<TD ALIGN="center" VALIGN="bottom"><A HREF="web.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="right"  VALIGN="bottom"><A HREF="web_param.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
</TR>
</TABLE>



<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>&nbsp;&nbsp;&nbsp;
<A HREF="copyright.html">Copyright &copy; Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>

</FONT>
</TD>
</TR>
</TABLE>


</BODY>

<!-- *********************************************************************** -->
<!--      End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/)       -->
<!-- *********************************************************************** -->

</HTML>