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