NAME
    Template Toolkit - a Perl toolkit for processing templates and building 
    template applications.

OVERVIEW
    The Template Toolkit is a collection of Perl modules which
    collectively implement a fast and powerful template processing
    system. In this context, a template is a text document which
    contains embedded processing "directives". These directives
    instruct the template processor to perform certain actions and
    collectively constitute the *language* that the toolkit
    implements. Anything not specially marked as a template
    directive is treated as plain text and gets passed through
    intact. You can choose what mark-up tags to use but in the
    default case, directives are embedded [% like this %].

    The toolkit is designed to be fast, flexible and easy to use,
    allowing you to construct entire content systems from a number
    of small, reusable components. It can be customised, modified
    and extended to serve in almost any template-based application.

    It is ideally suited for generating web content, but it is by no
    means limited or specific to this or any other application area.
    Instead, it supports a simple "plugin" interface for dynamically
    loading extension code to satisfy different requirements. It
    encourages the clean separation of user interface elements (sub-
    templates) and code (plugin modules or other Perl objects/code),
    promoting flexibility, re-use and ease of development and
    subsequent maintenance.

    The toolkit is a direct descendant of, and replacement for the
    Text::MetaText module. It has been designed and rebuilt from
    scratch based on several years of experience gained from
    developing, supporting and using Text::MetaText and other
    template processing applications and tools. It is an Open Source
    project in which contribution and collaboration are strongly
    encouraged.

FEATURES
    -   Fast, flexible, generic and open template processing system.

    -   Simple template "micro-language" provides basic functionality to
        manipulate variables (GET/SET), process other template
        component files (INCLUDE), iterate through various values
        (FOREACH) and conditional branching (IF/ELSIF/ELSE).

    -   More complex application code can be developed in Perl (or C,
        C++, etc) and maintained separately. Template processor
        binds user code to variables to provide access to
        application functionality from templates.

    -   This natural extensibility promotes the separation of the
        application from the interface. Template documents remain
        simple and focussed on rendering the interface. Application
        code can be made more generic by concentrating on what the
        application does, not what it looks like.

    -   Ideally suited, but not limited to, web content generation.
        Front-end modules and/or scripts provided for use with
        static pages, CGI scripts, Apache/mod_perl handlers, etc.

    -   Template documents parsed by a fast LALR(1) parser which is
        generated from a YACC-like grammar. Parse::Yapp is used to
        compile the grammar. Parser grammar can be modified and re-
        compiled to create custom template languages.

    -   Parsed template documents are compiled to an intermediate form
        and cache. They can subsequently be rendered repeatedly in
        minimal time.

    -   Stash object manages references to complex external code and
        data and provides a simple template interface via bound
        variables.

    -   Variables may be partitioned into nested namespaces.

    -   Custom error handling and recovery mechanisms implemented as
        basic exception handling. Users can define template blocks
        to be processed automatically when errors occur and define
        the subsequent course of action.

    -   Iterator objects can be created to handle complex set iteration.
        This is handled transparently by the FOREACH directive.

    -   Provides an extensible framework for other template languages,
        processors and applications.

    -   Template language is independent (theoretically at least) of the
        implementation language, platform, operating system, etc.

    -   Extensive documentation, test suite, examples, etc.

    -   Fully open source code. Contributions, collaborations,
        suggestions and other feedback welcome.

    -   Mailing list: send email to majordomo@cre.canon.co.uk containing
        the text "subscribe templates".

PREREQUISITES
    At present, the Template Toolkit requires Perl 5.005. Efforts
    will soon be made to support *some* earlier versions (e.g.
    5.004).

OBTAINING AND INSTALLING THE TEMPLATE TOOLKIT
    The Template Toolkit module bundle is available from CPAN. As
    the 'perlmod' manual page explains:

        CPAN stands for the Comprehensive Perl Archive Network.
        This is a globally replicated collection of all known Perl
        materials, including hundreds of unbundled modules.  
        [...]
        For an up-to-date listing of CPAN sites, see
        http://www.perl.com/perl/ or ftp://ftp.perl.com/perl/ .

    The module is available as:

        /authors/id/ABW/Template-Toolkit-<version>.tar.gz

    Unpack the archive to create an installation directory.
    Something like this:

        zcat Template-Toolkit-<version>.tar.gz | tar xvf -

    'cd' into that directory, make, test and install the modules:

        cd Template-Toolkit-<version>
        perl Makefile.PL
        make
        make test
        make install

    The 't' sub-directory contains a number of test scripts that are
    run when a 'make test' is run. You may find some of the examples
    to be enlightening and others perplexing.

    The 'make install' will install the module on your system. You
    may need administrator privileges to perform this task. If you
    install the module in a local directory (for example, by
    executing "perl Makefile.PL LIB=~/lib" in the above - see
    `perldoc MakeMaker' for full details), you will need to ensure
    that the PERL5LIB environment variable is set to include the
    location, or add a line to your scripts explicitly naming the
    library location:

        use lib '/local/path/to/lib';

MAILING LIST
    A mailing list exists for up-to-date information on the Template
    Toolkit and for following and contributing to the development
    process. Send email to majordomo@cre.canon.co.uk with the
    following message in the body:

      subscribe templates

AUTHOR
    Andy Wardley <abw@cre.canon.co.uk>

      http://www.kfs.org/~abw/
      http://www.cre.canon.co.uk/perl

VERSION
    This is version 0.22 of the Template Toolkit.

    It is a stable beta release version preceding the imminent
    release of version 1.0.

    Please consult the Changes file for information about visible
    changes in the Template Toolkit between releases. The TODO file
    contains details of known bugs, planned enhancements, features,
    fixes, etc.

COPYRIGHT
    Copyright (C) 1996-1999 Andy Wardley. All Rights Reserved.
    Copyright (C) 1998-1999 Canon Research Centre Europe Ltd.

    This module is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.

