<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>
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.
Finding The WebMake File
~~~~~~~~~~~~~~~~~~~~~~~~
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.
The WebMake File Structure
~~~~~~~~~~~~~~~~~~~~~~~~
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 <a
href=$(format)>**<webmake>**</a> tag.
**Options and libraries**: Quite often, you may want to use some of the <a
href=$(use)>optional plug-ins</a> provided with WebMake, or occasionally, you
might need to <a href=$(option)>set options</a> 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 <a href=$(contents)>content text</a>, <a
href=$(templates)>HTML templates</a>, or <a href=$(media)>URLs of media
files</a> (such as images), from directories in the filesystem.
**Inputs embedded in the WebMake file**: Another key area. <a
href=$(content)>Content text</a>, <a href=$(template)>HTML templates</a> and
tables of small items of <a href=$(contenttable)>content</a> or <a
href=$(metatable)>metadata</a> 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" [$(metadata)] is
the way to do it. WebMake supports several ways of tagging your content with
metadata to provide this. Metadata can be <a href=$(wmmeta)>embedded into the
content text</a>, or <a href=$(metatable)> tagged onto the content</a> 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 href=$(sitemap)>a site map</a>, <a
href=$(navlinks)>back and forward navigation links</a>, and <a
href=$(breadcrumbs)>''breadcrumb trails''</a>. You can also write your own <a
href=$(perl)>Perl</a> code to generate custom indexes using the <a
href=PerlCodeLibrary.pm.html>library functions</a>, if you prefer.
**Outputs**: Finally, all that data needs to be written somewhere. The <a
href=$(out)>out</a> tag takes care of this. Each <a href=$(out)>out</a> block
is roughly equivalent to a __target__ in traditional UNIX __make(1)__
terminology; the text inside the tag is expanded (by expanding <a
href=$(content_refs)>&wmdollar;{content references}</a>) 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 <a href=$(for)>for tag</a> is
useful here to automate the process.
**The footer**: Finally, the WebMake file ends with a
<a href=$(format)>**</webmake>**</a> tag.
Which Outputs Are Created?
~~~~~~~~~~~~~~~~~~~~~~~~~
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''.
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, 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.
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.
