• 1 Introduction
• 2 Copyright, licensing, availability and acknowledgements
• 3 Revision History
• 4 Using the macro expander
  • 4.1 Building a Table of Contents
  • 4.2 Adding horizontal rules after sections of a given level
  • 4.3 Adding links back to the table of contents
  • 4.4 Creating indices
  • 4.5 Adding entries to a subject or keyword index
  • 4.6 Creating per-user settings files
  • 4.7 Adding a header and footer
  • 4.8 Using the built-in "quickie" tags
  • 4.9 Defining your own "quickie" tags
  • 4.10 Using replacement macros
  • 4.11 Inserting the date of last document translation
  • 4.12 Including other files
  • 4.13 Embedding Perl code
• Index

To use the macro expander, create a file containing WebMacro tags, (let's say, mydoc.htp) and pass it through the expander:

   webmacro < mydoc.htp > mydoc.html

You could call your master document mydoc.htp, and build a makefile which converts .htp files to .html files by passing them through WebMacro.

Contents

This software was partly developed while working for my employer, Petroleum Exploration Computer Consultants, and Enigma Data Systems. Thanks to Dr. Ugur Algan for allowing me to release WebMacro under the GPL.

Thanks also to the following users of WebMacro for providing several excellent suggestions for improvements:

• Mark Clegg
• David Crosta

To download the latest version, click this link: ( bytes)

webmacro-0.03.tar.gz

Please let me know if you'd like any changes making to WebMacro. I maintain a small mailing list for announcements and discussions about it - please mail me to be added to it.

Contents

• 19th June 1998: Released version 0.01 via my home page.
• 12th January 1999: Released version 0.02 via my home page. Added the BOX macro to the standard distribution, added the INCLUDE directive, added the ability to perform macro expansion with variable interpolation.
• 7th July 2000; Released version 0.03. Added TOCLINKS tag from Mark Clegg, some useful quickie tags from me, and EVAL, the possibilities of which are just too staggering to comprehend. INDEX and INDEXREF were added after a suggestion from David Crosta. IDX and the subject/keyword index now works.

   <H1>First main section</H1>
   blah...
   <H2>First subsection</H2>
   more blah...
   <H2>Second subsection</H2>
   more blah...
   <H1>Second main section</H1>

This is an ideal candidate for automation :-)

WebMacro will automatically scan through your document for heading tags, and build them into a table of contents. It will add section numbers automatically to both the table of contents entries, and the section headings in the main document, should you so desire.

To add a table of contents, simply place a <TOC> tag at the place you want the table to appear.

To turn on section numbering, place a <TOCNUMBERS> tag before the first section heading you use.

To disable section numbering - for instance, just before your appendices - place a <NOTOCNUMBERS> tag before the next section heading. The following appendix section headings should then be declared with <H1>A. Whatever title</H1> - WebMacro does not yet perform automatic appendix numbering (or should that be lettering?).

Numbered sections are off by default.

To place a section heading in your document that will be ignored by the heading scanner, place a <TOCIGNORE> tag immediately before the <Hx> tag. This is useful for the heading called "Table Of Contents". You might want a heading claled this, but you might not want it to appear in the table of contents itself. Usually, you would write the following:

   <TOCNUMBERS>
   <TOCIGNORE><H1>Table of Contents</H1>
   <TOC>
  

   <SECTIONRULE 2>

For example, this document uses:

   <TOCLINKS !<P ALIGN="RIGHT">Contents</P>!>

WebMacro can automate the building of these indices. You still have to do the work of adding IMG SRC="....." whenever a picture is included in your document, but in order for WebMacro to add an entry in a specific index, use the tags <INDEXREF iname>some caption</INDEXREF>

Here, iname is an index name. For example:

   ... some complex looking bit of maths ...
   <INDEXREF EQUATIONS>Schrödinger's Wave Equation</INDEXREF>

   <INDEX EQUATIONS>

Quantum Mechanical Illustrations
4.0 Schrödinger's Wave Equation
4.1 Dirac's Equation
4.2 A Feynman Diagram
4.3 Hawking Radiation

4.5 Adding entries to a subject or keyword index

To create this, you need to place index entries throughout your document, at places where you're referring to new concepts. These index entries will be collected, and built into a subject index, which is usually placed at the end of the document.

To insert the subject index, use the <INDEX> tag. You may want to define a section heading before it (usually containing the phrase "Index") - you may want to use the <NOTOCNUMBERS> tag before this, so that the index doesn't get given a section number.

Defining individual entries to be collected into the index is a little more complicated. There are several forms, and the syntax is tricky.

Supposing you want an entry in the index indicating where in your document you are starting to talk about left-handed flange benders (!). You would write your first words thusly:

   <IDX>left-handed flange bender</IDX>
   In 1879, Pierre la Vache invented the 
   left-handed flange bender.  It was an instant success....

   In 1879, Pierre la Vache invented the 
   left-handed flange bender. 
   It was an instant success....

Your treatise on the left-handed flange bender will probably require several index entries, relating to different facets of this intriguing device. To support the creation of grouped index entries, you may supply a context for the index reference. The following example will help clarify this:

   <IDX>left-handed flange bender(invention)</IDX>
   In 1879, Pierre la Vache invented the 
   left-handed flange bender.
   It was an instant success....
   ... several pages later ...
   <IDX>left-handed flange bender(handedness)</IDX>
   Mass adoption of the device did not take place until 1892, when the
   handedness of the device was questioned by John Cuckson. 
   <IDX>left-handed flange bender(history)</IDX>
   In his landmark text on the subject, A Natural History of Flange 
   Deforming Devices......

One use for this is to define a standardised header and footer for all your documents.

Note that this option is per-user, so when one user builds a document, they'll get their .webmacros, whereas another user would get their set, which will probably be different.

So if you want a library of macros used throughout all of your organisation's documents, it may be better to create this in a separate file, and use the <INCLUDE> tag.

4.7 Adding a header and footer

Similarly, for the footer, use <FOOTER> and </FOOTER> tags.

Note: these tags must appear on their own, on a separate line all to themselves. The contents of the header and footer can span multiple lines.

   <FONT COLOR="#00C000">green text</FONT>

   <GREEN>green text</GREEN>

• <RED>
• <GREEN>
• <BLUE>
• <YELLOW>
• <CYAN>
• <PURPLE>

Use <PAPER> in place of <BODY> and </PAPER> in place of </BODY> to create a document with a white background with nicely-coloured links.

Note: you can't use <PAPER> in conjunction with <HEADER>. Just use <HEADER> and then place <PAPER> inside your header. Similarly for the ending tags.

Use <NOTE> to create indented notes, with a "Note:" at their start, like the one above.

If you want to put text in nice boxes, you can use the <BOX>...</BOX> directives. The box will be created with a black border and white background. Sorry if these colours aren't your style. You can always redefine the BOX macro.

Boxes will expand to fit - if you want a narrow column (like this) you have to add BR line breaks yourself

4.9 Defining your own "quickie" tags

   <DEFTAG NAME=!GREEN! PRE=!<FONT COLOR="#00C000">!  POST=!</FONT>!>

You don't have to provide a post-string, if you don't need one. You can use this to create short-cuts for large commonly-used pieces of HTML.

There is also another tag, <DEFBLK>. This allows you to create large, multi-line blocks of text, and use a name to abbreviate them. for instance:

   <DEFBLK logo>
   LL
   LL      ooo   ggg   ooo
   LL     o   o g   g o   o
   LLLLLL  ooo   gggg  ooo
                    g
                gggg
   </DEFBLK>
   ...
   <logo>

   <DEFBLK MYBLOCK>
   This is a block of text
   containing the word `$0'
   which will be replaced 
   in the macro expansion.
   </DEFBLK>

   <DEFTAG NAME=!MYVAR1! PRE=!Oh what a lovely day!>

   <MYBLOCK>

   <MYBLOCK artichoke>

   <MYBLOCK $MYVAR1>

   <DEFBLK ART>
   <TABLE BGCOLOR="BLACK" BORDER=0 CELLPADDING=1 CELLSPACING=0><TR><TD>
   <TABLE BGCOLOR="WHITE" BORDER=1 CELLPADDING=10 CELLSPACING=0>
   <TR><TD>$0</TD><TD>$1</TD></TR>
   <TR><TD>$2</TD></TR>
   </TABLE></TD></TR></TABLE>
   </DEFBLK>

   <ART fred bert sydney>

On its own, the block looks like this:
This is a block of text
containing the word `$0'
which will be replaced 
in the macro expansion.


But with macro expansion, you can do this:
This is a block of text
containing the word `artichoke'
which will be replaced 
in the macro expansion.


Or, if you want to reference another block inside the macro:
This is a block of text
containing the word `Oh what a lovely day'
which will be replaced 
in the macro expansion.


And here's a slightly more complex example...




fred
bert
sydney

The macro arguments are split on whitespace; there is no quoting mechanism. You'd have to assign arguments containing spaces to a block, as in $MYVAR1 above. <MYBLOCK Oh what a lovely day> has five arguments, not one, and they'll be assigned to $0..4.

One of my favourite uses for this is to avoid having to type a URL twice. For instance, you can get to the Perl language home page with this link. However, if you print this document out, you'll have no idea where that link points to. So, if you want to do it the hard way, you would use the following HTML:

   <A HREF="http://www.perl.com">http://www.perl.com</A>

   <DEFTAG NAME=!LINK! PRE=!<A HREF="$0">$0</A>!>

In fact, I like <LINK> so much, I made it part of the built-in quickie tags in 0.03.

4.11 Inserting the date of last document translation

For example you might do:

   Here is my main document
   <INCLUDE bigmacros.htp>
   

This, and Perl's intelligent open command can be exploited nicely:

   <INCLUDE ls -lh downloadable.tar.gz | awk '{ print $5 }'|>

This allows you to insert the output of pretty much any shell commands in the output of WebMacro (with macro expansions performed on them). Thanks to Mark Clegg for pointing that out.

This option can be used to build up a library of macros used in all your documentation. At the top of your documents, you'd do:

   <INCLUDE housestyle.htp>

   <DEFEVAL CUBE>
   $0 * $0 * $0
   </DEFEVAL>

   The value of 27<SUP>3</SUP> is <CUBE 27>.

This was used to show you the size of the current WebMacro downloadable archive above. Here's how, showing the size of the webmacro source code:

   <DEFEVAL FILESIZE>
   (stat("$0"))[7]
   </DEFEVAL>

   The size of webmacro is currently <FILESIZE webmacro>.

WebMacro will report the line number and error should your eval fail. Note that I supplied quotes around the argument in stat, above. You'll need to supply quotes too, or you'll get bareword problems.

If you know the internal operations of WebMacro, this option really opens up a whole world of possibilities.

Here's a slightly more advanced example. Given a numeric argument, build up a square out of # characters, with sides of that length.

   <DEFEVAL SQUARE>
   my $len = $0;
   my $out = "<PRE>\n" . ('#' x $len) . "\n";
   my $sqline = '#' . (' ' x ($len-2)) . "#\n";
   $out .= ($sqline x ($len-2));
   $out .= ('#' x $len) . "\n</PRE>\n";
   $out;
   </DEFEVAL>

########
#      #
#      #
#      #
#      #
#      #
#      #
########