NAME
    metapage - perl 5 utility for processing files using MetaText
    module.

USAGE
        metapage [@cmdfile] [-vqdrafmth] file [ file [...] ]

        -v   verbose mode
        -q   quiet mode - shut up about missing files
        -d   debug mode 
        -r   recurse into sub-directories
        -a   make all files (implicit -r)
        -f   force pages to be rebuilt even if source is not modified
        -m   file modification date sets FILETIME variable (default)
        -t   today's date/time sets FILETIME variable
        -h   this help

DESCRIPTION
    The metapage utility uses the Text::MetaText module to process
    files. It acts like the Unix make(1S) utility, traversing a
    document tree and attempting to determine which files have been
    updated (by comparing the date stamp of the source file with
    it's corresponding processed destination file). Files that are
    identified in this way, or explicitly specified by name or by
    using the `-f' (force) flag, are processed using a
    Text::MetaText object and the resulting output is written to
    each corresponding destination file.

CONFIGURATION
    The metapage utility first looks for a `.metapagerc' file in the
    user's home directory. The `sample.metapagerc' file in the `bin'
    sub-directory of the MetaText distribution can be used as a
    basis for your own configuration file. Copy this file to your
    home directory, name it `.metapagerc' and edit accordingly. e.g
    (from MetaText distribution directory)

        cp bin/sample.metapagerc ~/.metapagerc

    The configuration file can contain (up to) four distinct blocks
    which each determine the required configuration for an aspect of
    metapage's use. Each block commences in the configuration file
    with a line indicating the block name in square brackets (e.g.
    "[file]"). Any lines following this block definition (up to any
    subsequent block definition) are considered part of the block.
    Block names and configuration items may be specified case
    insensitively.

    A typical `.metapagerc' file is shown here:

        [file]
        src         = ~/websrc/docs
        lib         = ~/websrc/lib
        dest        = ~/web
        ignore      = \b(CVS|RCS)\b
        ignore      = \.gif$

        [profile]
        dir         = ~/etc/metapage
        default     = abw

        [config]
        delimiter   = ,
        debuglevel  = info,process,data

        [define]
        images      = /images
        cgibin      = /cgi-bin
        home        = /index.html
        abw         = "Andy Wardley"

    The configuration blocks and their associated values are as
    follows:

  FILE

    The [file] block include items which specify the various
    directory trees on which metapage should work. Note that any
    directories specified in metapage configuration files may start
    with a "~" or "~<uid>" to represent the current user's, or the
    named user's home directory respectively. The sample
    configuration above demonstrates this.

    SRC `src' defines the root directory under which all source
        ("template") files should reside. Thus the command `metapage
        foo/bar.html' instructs metapage to process the file
        "foo/bar.html" relative to the `src' directory.

    DEST
        `dest' defines the root directory of the "destination" tree
        where processed files are output to. Specifically, for a
        given <file>, metapage processes the file <src>/<file> and
        saves the output to <dest>/<file>.

    LIB `lib' lists the root directory (or directories - each separated
        by a colon ':') where INCLUDE'd files are to be found. This
        is the equivalent to setting the LIB configuration option
        directly in the Text::MetaText object

    ACCEPT
        The `accept' and `ignore' options are used to specify which
        files in the source directory should or shouldn't be
        processed. By default, all files are considered (but may not
        actually be processed if the source file is older than the
        corresponding destination file). If one or more `accept'
        values are specified, the only files considered will be
        those that match one of the `accept' patterns. The value
        should be a perl-like regular expression. Multiple `accept'
        options may be specified.

    IGNORE
        Like the `accept' option described above, the `ignore'
        option is used to specify a file pattern or patterns. In
        this case, the patterns are used to determine which files
        should *not* be processed. This is useful to tell metapage
        to ignore images, source control directories (RCS, CVS, etc)
        and so on. The value should be a perl-like regular
        expression. Multiple `ignore' options may be specified.

        Note that `accept' and `ignore' patterns are applied to file
        names *relative* to the `src' directory. e.g.
        `public/foo.html' rather than
        `/user/abw/websrc/public/foo.html'

    Example:

        [file]
        src    = ~/websrc/docs
        dest   = ~/public_html
        lib    = ~/websrc/lib
        accept = ^public\/
        accept = ^shared\/           
        ignore = \b(RCS|CVS)\b
        ignore = \.gif$

  PROFILE

    The <metapage> utility allows multiple configuration profiles to
    be defined and loaded from the command line (prefixed by an '@'
    symbol). e.g.

        metapage @profile ...

    Each "profile" is a configuration file which can contain any of
    the valid metapage items described in this section.

    The [profile] block defines the location of these additional
    configuration files (`dir') and the default profile, if any, to
    use (`default').

    DIR `dir' specifies the location of any additional configuration
        "profile" files. Profiles specified on the metapage command
        line are read from this directory.

    DEFAULT
        `default' names a default profile (in the directory
        specified above) which should be loaded regardless of any
        other command line profiles specified. Configuration files
        are processed in this order:

            ~/.metapagerc
            ~/<profile-dir>/<default-profile>     # e.g. default = abw
            ~/<profile-dir>/<specific-profile>    # e.g. @web

    Example:

        [profile]
        dir     = ~/etc/metapage
        default = abw

  CONFIG

    The `[config]' section allows variables to be defined that
    relate directly to the configuration of the Text::MetaText
    object. See `perldoc Text::MetaText' for details of the
    configuration items available. Note that there is no facility to
    specify multiple values, code blocks, etc., from within the
    configuration file and as such, only those configuration items
    that take simple scalars can be specified.

    The `lib' configuration value specified in the `[file]' block is
    also passed to the Text::MetaText configuration and does not
    need to be explicitly added to the `[config]' section.

    Example:

        [config]
        case    = 1
        chomp   = 1
        execute = 2
        rogue = warn,delete

  DEFINE

    The `[define]' sections allows variables to be pre-defined for
    evaluation in all files subsequently processed by metapage. This
    is useful for defining common elements (such as email address,
    default author name, copyright message, etc) that may be
    scattered throughout many documents but can be updated en masse.

    Example:

        [define]
        email   = abw@kfs.org
        name    = "Andy Wardley"
        imgurl  = "/~abw/images"
        homeurl = "/~abw/"

    metapage, without any further variable definitions, will then
    correctly process the file:

        <a href="%% homeurl %%/index.html">
        <img src="%% imgurl %%/misc/abw.gif" alt="%% name %%">
        </a>

    generating the output:

        <a href="/~abw/index.html">
        <img src="/~abw/images/misc/abw.gif" alt="Andy Wardley">
        </a>

    Note that it is possible to embed variable names (prefixed by
    '$') within variable definitions. These are then evaluated by
    Text::MetaText during substitution. Variables that are not
    explicitly separated from other text by non-word characters can
    be enclosed in braces to disambiguate them.

    Examples:

        [define]
        server   = www.kfs.org
        docs     = /~abw       
        index    = index.html
        homepage = $docs/$index
        images   = $docs/images
        homeurl  = http://${server}${docs}/$index

COMMAND LINE OPTIONS
    The default behaviour for metapage is to process all and any
    files specified on the command line. All files are considered
    relative to the `src' option in the `[file]' block of the
    configuration file.

    Example:

        metapage index.html manual.html about.html

    The following command line options affect how metapage works:

    -v (Verbose Mode)
        In verbose mode, metapage generates informational messages
        about the files it is processing.

    -q (Quiet Mode)
        In quiet mode, metapage ignores any "File not found"
        messages which are normally generated when a specified file
        does not exist or cannot be read.

    -d (Debug Mode)
        Additional debug messages are generated in debug mode. This
        can be useful for testing the correctness of metapage and
        the Text::MetaText module and also to trace any formatting
        problems that may be caused by an incorrect directive in the
        source text.

    -r (Recurse)
        With the recurse option specified, it is possible to name a
        directory on the command line and have metapage recurse into
        the directory and process all modified files within.

    -a (All Files)
        When the "all files" option is specified, metapage traverse
        the entire document source tree and processes any updated
        files contain within. The "Recurse" (`-r') option is
        implicitly set.

    -f (Force Update)
        In normal usage, metapage only processes files whose source
        file has been modified more recently than the destination
        file (or indeed, if there is no destination file). In
        "force" mode, all specified files are updated regardless.

    -m (Modification Time)
        By default, metapage examines the file modification time of
        each source file and sets the Text::MetaText variable
        FILETIME to represent this value (in seconds since the
        epoch, 00:00:00 Jan 1 1970 - see time(2)). See the TIME
        variable in the SUBST section of the section on "METATEXT
        DIRECTIVES" in the Text::MetaText documentation (`perldoc
        Text::MetaText') for information on formatting time-based
        values.

        This is useful for adding a line such as:

            File last modified: %% FILETIME format="%d-%b-%y" %%

    -t (Today Time)
        The `-t' option overrides the above behaviour and sets the
        FILETIME variable to the current system time. In this case,
        the previous example would be more accurate to read:

            File processed on %% FILETIME format="%d-%b-%y" %% 

    -h (Help)
        This option displays a help message indicating the command
        line options for metapage.

    In addition to command line options, one or more "profile"
    configuration files can be specifed (each prefixed by '@'). Each
    configuration file named will be examined and acted upon in turn
    (after the .metapagerc and any `default' profile). The
    configuration files should reside in a directory named by the
    `dir' element in the `[profile]' block of the `.metapagerc'
    file.

    Example:

        metapage -vaf @abw @kfs  # force (-f) process all files (-a) verbosely
                                 # (-v) using profiles 'abw' and 'kfs'

  PRE-DEFINED VARIABLES

    As mentioned in the section above, the FILETIME variable is set
    by metapage to indicate the source file modification time
    (default option - or explicitly set with `-m') or the current
    system time (`-t').

    Any files processed by metapage can include a SUBST directive
    (see `perldoc Text::MetaText') to substitute the appropriate
    value:

       File last modified: %% SUBST FILETIME format="%d-%b-%y" %%

    or, more succinctly:

       File last modified: %% FILETIME format="%d-%b-%y" %%

    Note that the CASE configuration option for Text::MetaText is
    disabled by default and as such, both `FILETIME' and `filetime'
    refer to the same variable. If case sensitivity is enabled (see
    the CONFIG manpage above) then the variable name should be
    specified in UPPER CASE. The following variables are set for
    each file metapage processes:

    FILEPATH
        The path (directory) of the current file relative to the
        source direcrtory. e.g. "/home"

    FILENAME
        The name of the file being processed. e.g. "index.html"

    FULLPATH
        The full destination path of the file, irrespective of the
        destination tree root. e.g.
        "/user/abw/public_html/home/index.html"

    FILEMOD
        The source file modification time in seconds since the epock
        (see time(2)). e.g. "886518480"

    FILETIME
        The source file modification time as per FILEMOD (default)
        or the current system time if `-t' specified.

AUTHOR
    Andy Wardley <abw@kfs.org> See also:

        http://www.kfs.org/~abw/
        http://www.kfs.org/~abw/perl/metatext/

    The metapage utility is distributed as part of the
    Text::MetaText package. See the appropriate documentation
    (`perldoc Text::MetaText') for more information on MetaText.

REVISION
    $Revision: 1.5 $

COPYRIGHT
    Copyright (c) 1996-1998 Andy Wardley. All Rights Reserved. This
    program is free software; you can redistribute it and/or modify
    it under the same terms as Perl itself.

SEE ALSO
    The Text::MetaText module.

