





                             The Wsmake User Manual
                              by Michael Brownlow


                      Edition 0.3, Applies to Wsmake 0.5.8


                    Copyright (c) 1999 by Michael Brownlow.
              $Id: manual.txt,v 1.14 1999/11/01 08:06:21 mike Exp $
===========================================================================
Contents:

Chapter 1. Introduction
    The introduction is long, you may want to search for the next chapter on
    wsmake usage if you are in a hurry. But do come back and read the
    introduction. It may help you in understanding why things are built the
    way they are, and hopefully enable you to provide some insight to the
    developers on design considerations. The developers want this tool to be
    versatile and strong, so we welcome all input from our end-users.

Chapter 2. Wsmake usage
    This chapter describes how to use wsmake. It covers the command line
    options and several ways in which the developers use wsmake.

Chapter 3. Configuration syntax
    Wsmake uses a configuration file to understand what it is supposed to
    do. This chapter describes all aspects of how a config file is built, and
    what options are allowed for each section.

Chapter 4. Examples
    Overviews of the examples provided with the wsmake package will be
    included here.

Chapter 5. Future
    There are many goals slated for our 1.0 release. But there are some new
    concepts that are being discussed which could be included in the 1.0
    release. This section describes some of those concepts and also how you
    can contribute to this effort.

Chapter 6. Licensing
    Here we describe what licenses that wsmake uses.

----------------------------------------------------------------------------

Detailed Contents:

Chapter 1. Introduction
 1.1 The need
 1.2 The design
  1.2.1 Configuration file
  1.2.2 Output
  1.2.3 Messenger
  1.2.4 Website Class
  1.2.5 Page Class 
  1.2.6 Page Types
   1.2.6.1 DefaultPage
    1.2.6.1.1 Parser
    1.2.6.1.2 Tag Substitution
    1.2.6.1.3 Page ordering
    1.2.6.1.4 Page Parts
    1.2.6.1.5 Database
   1.2.6.2 ExternalPage
    1.2.6.2.1 Database

Chapter 2. Wsmake usage
 2.1 Options
 2.2 Example usage

Chapter 3. Configuration syntax
 3.1 General Syntax
  3.1.1 Sections
  3.1.2 Attributes 
  3.1.3 Comments
  3.1.4 SubTags
 3.2 Website Section
  3.2.1 DefaultSetup Section  
   3.2.1.1 SubTagGroup Sections
   3.2.1.2 PagePart Sections
   3.2.1.3 PageOrder Sections
  3.2.2 DefaultPage Sections
  3.2.3 ExternalSetup Section
  3.2.4 ExternalPage Section

Chapter 4. Examples
 4.1 The Basics
 4.2 Using SubTags
 4.3 Using SubTagGroups
 4.4 Using PageParts and PageOrders
 4.5 Including files
 4.6 Nesting PageOrders
 4.7 CGI Scripts
 4.8 Menus

Chapter 5. Future
 5.1 Do you have a neat idea for wsmake?
 5.2 Concepts already considered
  5.2.1 "External" Pages
  5.2.2 Templates
  5.2.3 Admin tools
  5.2.4 GUI configuration
  5.2.5 Remote/Web administration
  5.2.6 Tailor options and output to that of GNU Make
  5.2.7 Target support
  5.2.8 Support for more databases

Chapter 6. Licensing


Document conventions:
* Footnotes are denoted as (see f#.) where # is the footnote number.
  Footnotes are at the bottom of this manual.

* There is occasionally a need to distinguish a word using quotes, double
  quotes, or other emphasizers. In this document, the following meanings
  are implied:

  Italics      : /word/          emphasis, reference
  Double quotes: "word"          string, reference, idea (e.g.)
  Single quotes: 'word'          exact string, no evaluations of string
  Back quotes  : `word`          command, example subtag (string)
  Quotation    : `word'          cite, exactness of expression, reference

* All emphasizers are literal. No punctuation will be in an emphasizer unless
  the punctuation is truly part of the value. For example:

  The name of the variable used is "test".

  The period is placed outside the emphasizer, rather than inside.

===========================================================================
Chapter 1. Introduction

  Welcome. This text is the manual for the program named wsmake. Wsmake is
  a website pre-processor. The basic function of this tool is to process a
  list of pages (defined by the administrator) from a "source" location
  into an "output" location.

  1.1 The need

    * Commonality and Re-use

      A frequent occurrence for many websites on the web is a common "theme"
      that each webpage uses. This "theme" could be as simple as a generic
      header and footer, or as complex as a menuing system with DHTML
      components. Whatever the case may be, the ease of replicating the
      "theme" across every page on the website varies greatly with the tools
      and the allowed functionality of the standards being used. In the
      early days of HTML, a popular way of making a theme was by using
      directives provided by the webserver to "include" extra information
      as it was requested from end-users. Another method, which seems to
      be the most popular for now (see f1.), is using CGI scripts. A CGI
      script would be able to dynamically create the theme for a webpage
      as it is requested as well. A relatively new way of creating dynamic
      web pages is by using languages embedded in the html. This allows for
      the re-use and commonality of themes too. Embedded languages are the
      most popular for web applications. PHP, WebSQL, and mod_perl are
      examples of embedded languages. Use of CGI scripts and embedded
      languages allows tremendous flexibility to how a page can be generated. 
      It is possible with simple include statements to achieve the commonality
      and re-use inherent to wsmake. But, they require for each page that
      needs to be common to be "executed" or parsed to generate the static
      common features. Wsmake can eliminate the need for this extra processing
      for static information. Granted it still must process the information,
      but only once for each update to the static content.

   * Less System Resource Consumption

      Considering the methods mentioned previously for webpage creation, it
      is apparent that there is a layer of execution happening for webpages
      that is not necessary for EVERY request of a webpage. It is this layer
      that wsmake abstracts. This results in less resource consumption for
      webpage creation and faster downloads for end-users.

   * Separation of content from interface
   
      In many organizations there is a need to publish electronic
      documentation on the web. These documents, however, are not meant
      to have HTML as their native format. As such, they are usually provided
      as a downloadable item, rather than content which can be viewed using
      the web browser. This causes several problems: first, it is assumed
      that every user needing the documentation has the necessary viewer
      to see the original document format. Second, if the user does have the
      necessary viewer, they will have to start a separate process for viewing
      the document. This has the potential of consuming too many resources in
      some operating environments. In many cases this turns out ok, but
      never-the-less, this is "extra" work laid on the user in order to see
      the data provided. In order to effectively publish data, it helps for
      it to be continuous in the environment the user is using to read the
      data. Publishing a small set (10-20) of documents by converting them to
      HTML or text from their original format is relatively easy to do. But
      when large volumes of information which are in continuous change are
      needed on the web, wsmake can help. (see f2.)

      Another benefit of separating content from interface is the ability
      to create a completely new "theme" for your website without interfering
      with the content that is to be displayed. But what about style sheets?
      Aren't they supposed to do this? In a way yes, but what style sheets
      really do is separate /presentation/ from content. So when I use the
      word "theme" I am referring more to the components of the presentation,
      rather than how the content it is presented.

   * Saving Time

      We need more time. This is fundamental. And wsmake can save you time.
      Using the current features already available in wsmake it is possible
      to save hours or even days worth of tedious work. For instance, consider
      a situation where you have a company name on every webpage on the
      website. Then the company name is changed, or needs modification. If
      the site had 10 pages, the task of making a change would be tedious, but
      certainly not a difficult task to accomplish in a short time. What if
      the site had 50 pages? In this case, assuming every occurrence of the
      company name is unique and constant on all of the pages, I could write
      a script to make the changes for me. But what about 1000 pages? Am I
      sure that the company name is the same for all pages? Will a simple
      script do? In this situation, there can be a tremendous time savings
      through the use of a tool like wsmake. Given that it would take me 7
      seconds to make the change for each page the old way, that would mean
      I would finish the name change in about 2 hours (without stopping!).
      With wsmake it would be finished in about two minutes. And I would only
      need to change the company name in one place. But this example is
      extreme. Even a site with 10 pages can bring relief to the webmaster if
      they only need to make the change in one place. I must note that
      converting a site with 1000 pages to use wsmake may not be easy in
      it's current version. But future versions should have tools for this
      type of mass conversion.

  1.2 The Design

    Wsmake has been through several design iterations, and there are probably
    a few left. Wsmake was made to enable re-use of the standard parts of a
    webpage. Out of this need many other capabilities were introduced. Wsmake
    is not limited to a website though. It's programming is abstract enough
    to allow an administrator to order any group of files to be compiled into
    a final version. With that main motivation in mind we have a foundation to
    explain how wsmake works. Currently wsmake draws away from traditional
    unix utilities where it can be used as a "pass-thru" program which accepts
    standard input and gives standard output. As the library and binary
    improve, it is expected that wsmake will ultimately be able to be used in
    that fashion. But for now a configuration file is needed for wsmake to
    know what to do. Much the same way that GNU Make uses a Makefile.

    1.2.1 Configuration file
		
      Currently the configuration file can hold one website. In the
      configuration file there are two main sections: Setup, Instances. The
      setup section is where various "global" entities are described. The
      instances section is where each "target" exists that wsmake should make.
      Wsmake uses parsers to manipulate the actual data. There is currently
      one such parser which is named "Default". In the configuration file we
      define DefaultSetup in the setup section, and DefaultPages represent
      the instances. Future parsers that are built in will follow the same
      naming. For instance, the next parser type to be built in is named
      "External". Therefore, there will be an ExternalSetup section and
      ExternalPage instances. For each parser, there can only be one Setup
      entity. All pages that are defined to use a particular parser have
      access to that parser's Setup section.

    1.2.2 Output

      Output is still under development. Currently several "debug" levels are
      allowed which alter the verbosity of the output. The default output
      consists of showing the user the current state of all Page instances,
      and then the process of making (parsing) the particular Pages that are
      in need of an update. With debugging set to higher levels, more
      information is reported about what wsmake was able to read from the
      configuration file.

    1.2.3 Messenger

      The messenger class is inherited by many of the classes in wsmake. The
      classes use print methods defined by Messenger for reporting information
      back to the user. The user communicates with the messenger for what
      level of output should be printed.

    1.2.4 Website Class

      The website class is the boss. It handles requests from wsmake to
      load, sync, make, dump, and print the website. For values of objects it
      maintains, it delegates the processing of these requests accordingly.
      The website class holds each parser's Setup and instances.

    1.2.5 Page Class

      The Page class is abstract. DefaultPage and soon ExternalPage are
      derivations of Page. The page class defines these six virtual methods:
        load
        sync
        make
        clean
        dump
        print
        printSync
      Each derivation then handles the actual implementation of those actions.
      So wsmake polymorphically builds the website by telling each Page to
      "make" itself. From the Website class perspective, wsmake does not know
      the type of Page being made, it only knows that Page's are able to be
      made. The same is true for the other virtual methods as well.

    1.2.6 Page Types

      There is currently one page type:
        DefaultPage          - The default parser of wsmake

      The following page type will be added soon:
        ExternalPage         - Provides the ability to use arbitrary parsers

      1.2.6.1 DefaultPage

        DefaultPage is a derivation of Page. It has the following features:
          * Tag substitution
          * Page ordering
          * Dependency checks
          * File inclusion
          * Grouping tags for substitution

        1.2.6.1.1 Parser

          The parser works on a line by line basis. It reads in a line from
          the source page, manipulates it, and writes it out to the output
          page. The parser will create the file if it does not exist. It
          also creates directories when necessary.

        1.2.6.1.2 Tag Substitution

          Tag Substitution is direct. With each line being parsed, wsmake
          looks for each occurrence of the defined tags and substitutes them
          directly for the value defined. Future versions may incorporate the
          use of regular expressions. Tag's are processed first by which
          group they are in, then by their order defined.

        1.2.6.1.3 Page ordering

          Default Pages have the capability of using a pre-defined order
          of pages to make the final page. The typical use is for applying
          a common header and footer. So the order would look like:
            header
            data
            footer
          Where data represents the data of the page that is using this
          order. PageOrders are defined in the DefaultSetup section. The
          header and footer above are references to pre-defined PageParts,
          which must be defined before the PageOrder. Each PageOrder has
          a name which is the token that is referenced by PageParts or
          DefaultPages that want to use that PageOrder.

        1.2.6.1.4 Page Parts

          PageParts are just like DefaultPages, except they are meant to
          be used by PageOrders, and they are not sent to the "output" area
          like the DefaultPages. PageParts have all of the features that
          a DefaultPage has. PageParts are defined in the DefaultSetup
          section in a location before they are used by PageOrders, and
          after PageOrders it uses.

        1.2.6.1.5 Database

          DefaultPages use a database to maintain the state of source pages
          and PageParts. It will eventually maintain the state of many other
          factors to solidify dependency checking. There is currently only
          one database used, which is BerkeleyDB. Support for other databases
          is under discussion. (see section 5.2.8)

      1.2.6.2 ExternalPage

        You want to use an ExternalPage if you have a program outside of
        wsmake that will handle the make (parse) process for the page. There
        are a large variety of pre-processors available that can be used with
        this function, or you could write your own pre-processor.


===========================================================================
Chapter 2. Wsmake usage

  The basic usage is like:

    shell$ wsmake -f configfilename

  This runs wsmake using the configuration file named "configfilename". Output
  defaults to always report the status of every page and then report each
  "make" instance. Typical output may look like:

    shell$ wsmake -f configfilename
    Upd templates/header.html
    --- templates/footer.html
    PoU html/index.html
      index.html        >...<
    shell$
	
  The first three lines show all Pages that are defined in "configfilename".
  The 3 character state on the left has the following possible output:

     ---    : This means there was no change since the last run
     Err    : This means that there was an error in determining the state of
              the Page. This could be because of:
                 Incorrect Permissions
                 Non-existent directories
                 Database problems
     New    : This means that the Page was not in the database on
              the last run, but now is.
     Frc    : This means that the Page will be updated regardless of it's state
     Upd    : This means that the Page was updated.
     NoO    : This means that the Page has no "output" file
     NoS    : This means that the Page has no "source" file
     Old    : This means that the "output" file is old
     PoU    : This means that this Page was updated because one of the
              PageOrders that the Page uses was updated.
     Unk    : Any state which cannot be determined by wsmake

  For all cases the page will be updated unless the state is ---, Err, or NoS.

  The last line shows that the index.html file was updated. The angle brackets
  represent the start and stop of the make process. The characters in between
  can be:

      .     : A piece of the page.
      i     : A file was "included" by one of the pieces.
      X     : A piece of the page was missing.
  
  2.1 Options

    Wsmake has the following options.

      wsmake [-Fqhvc] [-e|-s] [-d #] [-f configfile] [target] ...
       -F      : Force files to be updated regardless of their state.
       -q      : Quiet. No output.
       -h      : This help.
       -v      : Show version and copyright information.
       -c      : Clean the website.
       -e      : Targets match at end of web paths.
       -s      : Targets match anywhere in web paths.
       -d #    : Debug output level. (0-3)
                 0 = No output except for errors
                 1 = 0 and minimal output
                 2 = 1 and verbose output
                 3 = 2 and config file loading info
       -f file : Location of configuration file (looks for `wsmakefile'
                 if not specified)
       targets : Specific web paths, matching from front, to make. If
                 not specified, all pages will be made.

    "clean" is a special target name. When used, all other targets are
    ignored and the website is cleaned. To clean only certian groups of
    files, use the -c option with the targets but without the clean target.

  2.2 Example Usage

    Output all details:
       shell$ wsmake -d 3 -f website.conf

    Force build of entire website:
       shell$ wsmake -Ff website.conf

    Don't show any output except for errors:
       shell$ wsmake -d 0 -f website.conf

    Don't show any output at all:
       shell$ wsmake -q -f website.conf

    Make just index.html:
       shell$ wsmake -f website.conf index.html

    Use the default config file name `wsmakefile', and make all pages that
    end with "html":
       shell$ wsmake -e html

    Make all files in the help directory:
       shell$ wsmake -f website.conf help

    Clean the website:
       shell$ wsmake -f website.conf clean
         or
       shell$ wsmake -cf website.conf

===========================================================================
Chapter 3. Configuration syntax

  The wsmake configuration file is made up of sections. Some sections can
  only appear once in each configuration file. These are:

    Website
    DefaultSetup
    ExternalSetup

  All of the other sections can have more than one instance, however, there
  are restrictions to their location. In any given config file, the general
  layout is:

    Website
       DefaultSetup
          SubTagGroup
          ...
          PagePart
          ...
          PageOrder
          ...
       DefaultPage
       ...
       ExternalSetup
       ExternalPage
       ...

   Where indentations indicate sub sections and ... indicates an item which
   can occur more than once. For instance, SubTagGroups can have multiple
   instantiations, but must be in the DefaultSetup section, which must be in
   the Website section. The order that the items should be declared is the
   same order of their dependencies. I.e., If you define a DefaultPage, the
   DefaultSetup section must happen before it. If you define a PageOrder that
   uses a certain PagePart, that PagePart must be defined before the PageOrder.
   Etc...

   Details on what can reference what are described later in this chapter.

  3.1 General Syntax

    3.1.1 Sections
      Each section has the following syntax:

        Section {


        }

      The section name goes where "Section" is defined. The beginning and
      ending curly brace indicate that the contents within apply to that
      Section. Note that the first curly brace /must/ be on the same line
      one space after the section name. Also note that the ending curly
      brace must be on a line of its own. As wsmake matures, the config file
      format will loosen some in those respects.

    3.1.2 Attributes
      Attributes in each section are limited to one line and cannot exceed
      MAXLINELEN, which is 2000 characters. Attributes follow the following
      syntax:

        AttributeName  value

      The attribute's name goes where AttributeName is. The value is all
      characters after the name. This means you do not need quotations to
      include whitespace. However, leading and trailing whitespace are
      removed before processing, so quotations are necessary for leading and
      trailing whitespace. The valid quotation recognized is the double-quotes.
      E.g.

        name  "The Name value"

      In order to use a double quote inside the value, escape it with a '\':
		
        name  "The \"Name\" value"

      Note: The only escape sequence processed is the double quotes. Any
            other '\' usage is literal.

      Note: To have double quotes in the value, it is safest to escape them
            and enclose the entire value in double quotes. Otherwise output is
            undefined.

    3.1.3 Comments

      Comments can be defined by using the '#' character. Any data following a
      '#' is ignored by wsmake, unless it is within quotations of a value:

        url "http://mysite.com/index.html#about"

    3.1.4 SubTags

      SubTag attributes are a special type of attribute. They are defined in
      the same fashion of a AttributeName and value, but the value is made
      up of two parts:

        SubTag "SubTag Name" "SubTag Value"

      The value part is both the SubTag Name and SubTag Value together. The
      entire attribute must be all on one line.

  3.2 Website Section

    The Website section holds all information about a wsmake project. There
    can only be one Website section for each configuration file. The
    following sections can be defined in a Website section:

      DefaultSetup
      DefaultPage

    The following attributes can be defined in a Website section:

      Name       | Required? | Description
      -----------------------------------------------------------
      name       | no        | The name of the website
      maintainer | no        | The maintainer of the website
      url        | no        | The url of the website

    3.2.1 DefaultSetup Section  

      The DefaultSetup section holds common information for all DefaultPages.
      There can only be one DefaultSetup section for each Website section.
      The following sections can be defined in a DefaultSetup section:

        SubTagGroup
        PagePart
        PageOrder

      The following attributes can be defined in a DefaultSetup section:

        Name                   | Required? | Description
        -----------------------------------------------------------------
        lastmod_tagname        | no        | Internal subtag, replaced with
                               |           | last modification date of
                               |           | "source" file
        wsmake_version_tagname | no        | Internal subtag, replaced with
                               |           | version of wsmake used
        web_path_tagname       | no        | Internal subtag, replaced with
                               |           | web_path of current page
        source_tagname         | no        | Internal subtag, replaced with
                               |           | "source" page filename
        output_tagname         | no        | Internal subtag, replaced with
                               |           | "output" page filename
        header_tagname         | no        | Internal subtag, replaced with
                               |           | filename of header output for
                               |           | use with CGI scripts
        footer_tagname         | no        | Internal subtag, replaced with
                               |           | filename of footer output for
                               |           | use with CGI scripts
        include_tagname        | no        | Internal subtag, replaced with
                               |           | contents of file referenced, see
                               |           | details below
        database_filename      | yes       | Filename of database for this
                               |           | website
        source_dir             | no        | The default source directory
        output_dir             | no        | The default output directory
        part_dir               | no        | The default PagePart directory

      The format of the include_tagname value is special. The purpose of
      an include_tagname is for including files during the make process. The
      file to be included is defined for each use of the this subtag. For this
      tagname definition, we do not know the name of the file to be included,
      so this is labeled as '%s'. It is recommended that you provide a start
      and stop string before and after the '%s' that you want to use. For
      instance:

        include_tagname    "include(%s)"

      This means that for any occurrence in the HTML where the string
      "include(" is found with a filename after it and then a ")" will be
      replaced by the filename given:

        This is HTML. Now I will include a file: include(/web/include.txt).

      This will take the entire string "include(/web/include.txt)" and replace
      it with the contents of the file /web/include.txt.

      3.2.1.1 SubTagGroup Sections

        The SubTagGroup section defines a group of SubTags which can be reused
        by PageParts and DefaultPages. The following attributes can be defined
        in a SubTagGroup section:

        Name   | Required? | Description
        -----------------------------------------------------------
        name   | yes       | The name of the SubTagGroup
        SubTag | no        | A SubTag attribute

        There can only be one name for a SubTagGroup. SubTags may be defined
        0, 1, or many times.

      3.2.1.2 PagePart Sections

        The PagePart section defines a Page to be used as a piece of a
        PageOrder. The following attributes can be defined in a PagePart
        section:

        Name        | Required? | Description
        -----------------------------------------------------------
        name        | yes       | The name of the PagePart
        filename    | yes       | The filename of the pagepart (no directory!)
        directory   | no        | The directory that the file is in
        SubTag      | no        | A SubTag to use for this PagePart
        subtaggroup | no        | A SubTagGroup to use for this PagePart
        pageorder   | no        | A PageOrder to use for this PagePart
        parse       | no        | A value of NO, YES, INCLUDES_ONLY which
                    |           | tells how wsmake should parse this PagePart
                    |           | The default is YES

        There can only be one name, filename, directory, and parse attribute
        for each PagePart. The rest can have multiples defined. And they
        are applied to the PagePart in the order that they are defined.

      3.2.1.3 PageOrder Sections

        The PageOrder section defines a group of Pages to be used by PageParts
        and DefaultPages for ordering content. The basic idea is that you have
        a list of pages that comprise the header, and a list of pages that
        comprise the footer. The following attributes can be defined in a
        PageOrder section:

        Name | Required? | Description
        -----------------------------------------------------------
        name | yes       | The name of the PageOrder
        part | no        | A PagePart name to use
        data | yes       | The separator for header and footer information.
             |           | It has no value

        Here is an example PageOrder:

          PageOrder {
            name "Global"
            part "header"
            data
            part "footer"
          }

        Any page that uses this pageorder will have the PagePart whose name
        is "header" prepended to it and will have the PagePart whose name is
        "footer" appended to it in the "output" file. The "part" definitions
        are applied in the order that they are defined. There can only be
        one name and data definition for each PageOrder.

    3.2.2 DefaultPage Section

      The DefaultPage section defines a Page on the website. Each DefaultPage
      represents an item to be "made" by the make process. The following
      attributes can be defined in a DefaultPage section:

        Name        | Required? | Description
        -----------------------------------------------------------
        web_path    | yes       | The web path of the Page, i.e., the part
                    |           | after the http://servername/
        source_path | no        | The directory prefix to the web_path that
                    |           | represents the source information
        output_path | no        | The directory prefix to the web_path that
                    |           | represents the output location
        SubTag      | no        | A SubTag to use for this DefaultPage
        subtaggroup | no        | A SubTagGroup to use for this DefaultPage
        pageorder   | no        | A PageOrder to use for this DefaultPage
        page_type   | no        | A value of NORMAL, or CGI which tells wsmake
                    |           | the way it should output the header/footer
                    |           | information. The default is NORMAL.
        parse       | no        | A value of NO, YES, or INCLUDES_ONLY which
                    |           | tells how wsmake should parse this PagePart
                    |           | The default is YES
        cgi_header  | no        | This defines the name of the header file
                    |           | to output to (relative to the location of
                    |           | the output) for CGI page_types
        cgi_footer  | no        | This defines the name of the footer file
                    |           | to output to (relative to the location of
                    |           | the output) for CGI page_types

      There can only be one web_path, source_path, output_path, page_type,
      parse, cgi_header, and cgi_footer definition for each DefaultPage. When
      the page_type is CGI, the output of the header and footer information
      (if any) goes to the files defined by cgi_header and cgi_footer. If
      cgi_header or cgi_footer is not defined, "header.html" or "footer.html"
      is used as a default, respectively.

   3.2.3 ExternalSetup Section

      The DefaultSetup section holds common information for all DefaultPages.
      There can only be one DefaultSetup section for each Website section.

      The following attributes can be defined in a DefaultSetup section:

        Name                   | Required? | Description
        -----------------------------------------------------------------
        database_filename      | yes       |
        source_dir             | no        |
        output_dir             | no        |
        command                | yes       |
        options                | yes       |
        
   3.2.4 ExternalPage Section

        Name                   | Required? | Description
        -----------------------------------------------------------------
        web_path               | yes       |
        source_dir             | no        |
        output_dir             | no        |
        command                | no        |
        options                | no        |

     For options, '%s' is replaced by the full path to the source file and
     '%o' is replaced by the full path to the output file at make time.


===========================================================================
Chapter 4. Examples

  In this chapter we overview the set of examples that come with the wsmake
  package. The locations given are relative to the doc directory in the
  source package.

  4.1 The Basics

    Location: examples/ex1/README

    This example covers the minimal use of wsmake. It describes what to expect
    when running wsmake as well as the use of relative directories and the use
    of comments.

  4.2 Using SubTags

    Location: examples/ex2/README

    This example covers the use of SubTags in a webpage.

  4.3 Using SubTagGroups

    Location: examples/ex3/README

    This example demonstrates how to use SubTagGroups with webpages.

  4.4 Using PageParts and PageOrders

    Location: examples/ex4/README

    This example covers page-ordering and describes how the dependencies work
    out when updates are made.

  4.5 Including files

    Location: examples/ex5/README

    This example shows how to use the include_tagname attribute to have files
    "included" during the make process.

  4.6 Nesting PageOrders

    Location: examples/ex6/README

    This example shows how PageParts can have PageOrders. It also describes
    the order in which wsmake creates the pages that utilize this.

  4.7 Menus

    Location: examples/ex7/README

    This example shows one way of making a menu for a website using a
    combination of PageOrders, SubTagGroups, and SubTags

  4.8 CGI Scripts

    Location: examples/ex8/README

    This example shows how you can use CGI scripts with wsmake. It shows how
    header_tagname and footer_tagname can be used by the script to generate
    the final page.

  4.9 External Page

    Location: examples/ex9/README

    This example shows how to use other pre-processors instead of the one(s)
    built into wsmake.

===========================================================================
Chapter 5. Future
  5.1 Do you have a neat idea for wsmake?

    If you would like to see a feature in wsmake that hasn't been planned
    for, please email your ideas to the mailing lists. You can find
    instructions on how to join the lists at:

      http://wsmake.org/mailman/listinfo/

  5.2 Concepts already considered
    5.2.1 Templates

      Templates are a possible solution for large websites wanting to use
      wsmake. By large we mean greater than 50 webpages or so. Templates
      would be an extension of DefaultPages that allows you to specify a
      directory to be scanned for "source" html files and to parse them
      with the Template setting provided. There is still much discussion
      over the implementation of this feature. Another method proposed is
      to merely be able to list the pages individually, or with a pattern
      match, for a template that can be applied to the entire source area
      or specific directories.

    5.2.2 Admin tools

      Admin tools are needed for automated page additions and deletions to
      the config file. These tools would utilize the load and dump methods
      in the wsmake library. This may ease configuration of large sites.

    5.2.3 GUI for configuration

      A GUI to aid configuration for people who like a GUI

    5.2.4 Remote/Web administration

      A set of cgi scripts for editing and maintaining a website from remote
      locations.

    5.2.5 Support for more databases

      LDAP, flatfile, mysql, postgresql and others represent potential targets
      for state maintenance of DefaultPages. Another idea is to have wsmake
      retrieve "source" data of pages from these databases as well.

===========================================================================
Chapter 6. Licensing

  Wsmake may be copied only under the terms of either the Artistic License or
  the GNU General Public License, which may be found in the Wsmake source
  distribution.

  If you have any doubt about using wsmake in a way that may violate the
  license, please contact mike@wsmake.org and we'll discuss it.

===========================================================================
Footnotes:

F1. Now as of: $Date: 1999/11/01 08:06:21 $
F2. Currently wsmake would not be feasible to administer when a site becomes
    too large. But there are plans in the works to help soften this
    limitation. See "templates" and "admin tools" in the Future section
    above.
