WebMake Operation

First of all, WebMake relies on a WebMake file. This is an XML file, with a filename ending in .wmk, containing most of the important data on the structure, inputs and files that make up your site.

If you run WebMake without a -f or -R switch on its command-line, it'll first search for a file ending with .wmk in the current directory, then in the parent directory, and so on 'til it hits the root directory.

You can specify exactly which file to build from by using the -f switch. Alternatively if you use the -R switch, it'll search relative to the filename specified on the command-line; this is very handy if you're calling WebMake from a macro in your editor or IDE, as it means you don't even have to be running the editor in the same working directory as the files you're working on.

A WebMake file is made up of several conceptual chunks, as follows:

• the header
• options and libraries (optional)
• inputs: searching directories and data sources
• inputs: content embedded directly inside the WebMake file
• metadata (optional)
• catalog generation (optional)
• outputs
• the footer

The header: Every WebMake file must start with a <webmake> tag.

Options and libraries: Quite often, you may want to use some of the optional plug-ins provided with WebMake, or occasionally, you might need to set options to control WebMake's behaviour. The top of the WebMake file is a good place to do this.

Inputs: searching directories and data sources: The important bit! WebMake allows you to load content text, HTML templates, or URLs of media files (such as images), from directories in the filesystem.

Inputs embedded in the WebMake file: Another key area. Content text, HTML templates and tables of small items of content or metadata can be embedded directly into the WebMake file, for ease of editing.

Metadata: If you want your site to contain pages which list details about, or links to, other pages, generated on-the-fly, metadata is the way to do it. WebMake supports several ways of tagging your content with metadata to provide this. Metadata can be embedded into the content text, or tagged onto the content after its already been declared.

Catalog generation: once you've tagged your content text with metadata, WebMake can generate catalogs -- indexes, sitemaps, and the like -- from this. Built-in catalog types include a site map, back and forward navigation links, and "breadcrumb trails". You can also write your own Perl code to generate custom indexes using the library functions, if you prefer.

Outputs: Finally, all that data needs to be written somewhere. The out tag takes care of this. Each out block is roughly equivalent to a target in traditional UNIX make(1) terminology; the text inside the tag is expanded (by expanding ${content references}) and written to the named file. Since quite a lot of output is typically almost identical in terms of the templates it uses and they way it converts the output filename to the name of the content text to insert, the for tag is useful here to automate the process.

The footer: Finally, the WebMake file ends with a </webmake> tag.

Normally, all outputs named in the WebMake file are scanned, and possibly re-generated. However, if a target has been specified on the command line, only that file will be "made".

"Making" the target is not the end of it -- strictly speaking, the target may or may not be updated. WebMake tracks the dependencies of each file, and if these have not changed, the file will not be rebuilt.

That's the first optimisation. However it doesn't always work; if some of the file's text is generated by, or depends on text that contains dynamic Perl code, WebMake will always have to rebuild the file, as it cannot determine exactly what the Perl code is going to do!

To avoid continually "churning" the file, regenerating it every time WebMake is run, a comparison step takes place. Before the file is written to disk, WebMake compares the file in memory with the file on disk; if there are no changes, the on-disk file will not be modified in any way. This means tools like rsync(1), rdist(1) or even make(1) itself will work fine with a WebMake site.

All of these optimisations can be overridden by using the -F (freshen) command-line switch; this will force output whether or not the files have changed.

A very large (or very complicated) WebMake site can take a while to update. To avoid broken links while updating the site, WebMake generates all output into temporary files called filename.new; once all the output has been generated, these are renamed into place. This minimises the time during which there may be inconsistencies in the site.

Since WebMake uses dependencies to avoid rebuilding the entire site every time, it needs to cache metadata and dependency information somewhere.

Currently this data is stored in a file called filename/cache.db, where filename is a sanitised version of the WebMake file's name, in the .webmake subdirectory of your home directory.