The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-MetaText-0.22
River stage zero No dependents
++
/ metapage

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 
    -n   non-execute 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 its 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"

Note that quoted values, such as that in the last line of the example above, will have the surrounding quotes removed (the same applies for single quotes "'"). It is not obligatory to quote values with embedded whitespace in this manner as the parser will treat the entire line after the '=' as the configuration value (apart from any extraneous whitespace after the '=' or at the end of line).

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 pre-expanded by metapage before being passed to Text::MetaText for the processing phase. 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.

-n (No Execution Mode)

In no execution mode, metapage examines the source tree to determine which files should be processed but does not actually process them. Verbose mode (-v) is automatically set to print the file names and summary statistics. This is equivalent to the non-execute mode (also -n) of the make(1S) utility.

-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 "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' (as well
                             # as .metapagerc and any default profile)

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 FILETIME and other variables listed below should always be specified in UPPER CASE, even when case sensitivity is disabled (CASE == 0), as it is by default. Metapage uses the CASEVARS configuration item of Text::MetaText to identify these variables as special case-sensitive system variables. They cannot be re-defined (i.e. they're read-only) and should not conflict with any other user-defined variables of the same name (i.e. 'FILETIME' is entirely separate from some other 'filetime' variable). This behaviour only applies to the variables listed below.

The following variables are set for each file metapage processes:

FILEPATH

The path (directory) of the current file relative to the source directory. e.g. "graphics/index.html"

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

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 terms of the Perl Artistic Licence.

SEE ALSO

The Text::MetaText module.