<wmmeta name="Title" value="WebMake Operation" />
<wmmeta name="Section" value="01-intro" />
<wmmeta name="Score" value="20" />
<wmmeta name="Abstract">
what happens when you run WebMake
</wmmeta>

When you run WebMake, 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.

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.

Anyway, once it finds the WebMake file, it reads the file and parses it.
**Contents** and **media** statements will cause it to search directories or
other data sources for content (directly includable files and text blocks) or
media (static content that can be linked to or otherwise referred to with a
href).  **Include** statements will cause it to directly include a block of
code from another file.

Finally, once the WebMake file has been parsed, the list of **out**
files will have been read.  Each of these is roughly equivalent to
a __target__ in traditional UNIX __make(1)__ terminology.

If a target has been specified on the command line, that file will be made;
otherwise, all the **out** files named in the WebMake file will be made.

Dependencies And Other Optimisations
------------------------------------

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

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.

Ensuring A Seamless Transition
------------------------------

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.

Caching
-------

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.


