The Guava Tools
Frequently Asked Questions
The Guava tools are a set of Perl scripts for HTML preprocessing.
You can create multi-page documents with contents tables, or use
templates to give a consistent look to a set of pages. All output is
passed through the C preprocessor, so you can use directives such as
#include, #define, and #if. There are also a number of built-in
macros for producing dates, cross references, etc.
The Guava tools are designed for those who prefer to write their HTML in a text editor. If you prefer a graphical WYSIWYG environment you should probably look elsewhere. Personally, I use the Guava tools with XEmacs and GNU make.
The Guava tools might be of particular interest to C programmers,
since the preprocessor directives such as #include and #define are
identical to those used in C.
The Guava tools have been designed and tested on a Linux system with a runtime environment based on GNU tools. Other Unix systems should be equally suitable.
The hss2html program calls a C preprocessor to do some of the work. The default setting uses the 'gcc' program with the -E option, since not all systems have 'cpp' installed. If you do not have 'gcc' either you can specify an alternative program on the 'hss2html' command line.
The Guava tools are Perl scripts. You will need to have the Perl
interpreter installed on your system before you can use them. The
Guava tools have been tested with Perl version 5.004, although any
recent version should work just as well.
You can read about the Guava tools, and download them, from the Guava website.
If you need help, and your question isn't answered in this FAQ, or
on the website, please .
Most Guava macros are surrounded with angle brackets. If you want a word to appear with angle brackets in your output, you need to use the HTML <, and > codes. Similarly, if you need to produce an ampersand, use &. Since the source code does not actually contain the angle brackets, the macro will not be recognised by the Guava tools.
Preprocessor directives such as #include are only recognised by the C preprocessor when they are at the beginning of a line. If you need to begin a line with a '#', even if the following characters are not a valid directive, you need to do something to prevent the preprocessor from reading it. The simplest way is to indent the line with a space. If a space would cause problems in your output, you could use the <NOSP> macro.
The <NOSP> macro can also be used to break up words, and so prevent the C preprocessor from expanding macros such as LOCAL. If you need the word 'LOCAL' to appear in your output, use LO<NOSP>CAL.
Another technique, which is more appropriate when dealing with
large blocks of text, is to use <IMPORT> to import the
text from another file. Text imported in this way is inserted
directly into the output file with no processing. You will need to
ensure that any ampersands and angle brackets have been replaced with
the appropriate HTML codes.
Currently, the only difference between 'local' and 'remote' pages is the way the <FULLREF> macro is expanded. (Of course, you can always create other differences by testing the value of the LOCAL macro with #if).
When a page is built with the LOCAL macro defined, <FULLREF> leaves filenames unmodified. When building a remote page, <FULLREF> converts relative path names to an absolute path, and creates a full URL by replacing the root part of that path name with the address of your server. See the hss2html manual page for more details.
When you are browsing your own pages and you do not have a full time connection to your server, or when you are developing and testing your site, a set of 'local' pages is useful.
When you are ready to upload your pages, make a 'remote' build. I keep a 'remote' image of my site in a directory of its own, and use Joe Orton's sitecopy program, and a cron job, to update the server copy automatically when anything changes.
Since Guava version 1.0.4, the behaviour of the <FULLREF> macro
has been altered to read pairs of remote and local directory names from
a file supplied by the user. This allows more than one set of directories
to be supplied, making <FULLREF> useful even when the web
site is distributed across more than one server.
Here is an
that I have used myself.
If you have a single htt2html source file that generates many pages, you'll find that a change to the source that should affect only one page will in fact cause the HTML output for all pages to be regenerated. This can be particularly annoying if you use a tool like sitecopy that uploads pages that have been modified based on their date stamps.
Unfortunately it is not easy to use the normal methods (dependency information and 'make') to update individual pages from a single source file; It turns out that most pages depend on most others, particularly if you make extensive use of the <REF> macro. Consequently, 'htt2html -M' does not even attempt to produce dependency information suitable for this purpose.
The -d option has been added to hss2html and htt2html in Guava version 1.0.2 and later, and it provides a workaround for the problem. Using the -d option causes Guava to compare the generated files with any existing files of the same name, and replace them only if there are changes.
A disadvantage of using -d can arise when make thinks it needs to
recreate a file, but diff reports that the new file is the same as the
old one, so it is not updated. Subsequent invocations of make will
continue to attempt to update the file until the source changes in
such a way as to cause a real change to the output HTML. This
behaviour is mostly harmless.