The Guava Tools

Frequently Asked Questions

Home  Computer Software  Guava Main Page 

Frequently Asked Questions


1.1 What is Guava?

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.

1.2 Who is it designed for?

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.

1.3 What are the system requirements?

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.

1.4 Who wrote it?

Steve Morphet. <>

1.5 Where can I download Guava, or find out more?

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 .


2.1 How do I stop hss2html processing text inside <PRE> tags?

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 &lt, and &gt codes. Similarly, if you need to produce an ampersand, use &amp. 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.

2.2 Why would I want two copies of my web pages, local and remote?

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.

2.3 How do I set up a Makefile for my web site?

Here is an example makefile that I have used myself.

2.4 Why do files get regenerated when nothing has changed?

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.