[% META book = 'Release' page = 'README' %]

                                Template Toolkit

                                  Version 2.19

                                 27 April 2007

            Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved

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

    QUICK START (see INSTALL for further details)
    -----------

    The latest version of the Template Toolkit can be retrieved from:

        http://www.cpan.org/modules/by-module/Template/

    Fetch and install AppConfig 1.56 if you don't already have it installed.
    Available from CPAN in:

        http://www.cpan.org/authors/Andy_Wardley/

    To install the Template Toolkit:

        tar zxf Template-Toolkit-2.19.tar.gz
        cd Template-Toolkit-2.19
        perl Makefile.PL
        make
        make test
        make install

    The Makefile.PL will prompt for additional configuration options,
    including the installation of optional template libraries, HTML
    documentation and examples.  You can safely answer 'n' to all of these
    questions for a quick and basic installation.

    If you're running ActivePerl on a Win32 platform then you can use the
    Perl Package Manager (PPM) to install the Template Toolkit.  Chris
    Winters maintains a repository of pre-compiled PPM packages which contains
    the Template Toolkit, AppConfig and others.  For further information, see:

        http://openinteract.sourceforge.net/

    For further details on installation, see the separate INSTALL file.

    DESCRIPTION
    -----------

    The Template Toolkit is a collection of modules which implement a
    fast, flexible, powerful and extensible template processing system.
    It was originally designed and remains primarily useful for generating
    dynamic web content, but it can be used equally well for processing
    any other kind of text based documents: HTML, XML, POD, PostScript,
    LaTeX, and so on.

    It can be used as a stand-alone Perl module or embedded within an
    Apache/mod_perl server for generating highly configurable dynamic web
    content.  A number of Perl scripts are also provided which can greatly
    simplify the process of creating and managing static web content and
    other offline document systems.

    WHAT'S NEW?
    -----------

    Version 2.19 fixes some minor bugs in both Perl and XS versions of the Template
    Stash, and fixes a problem with a test in the test suite failing under Win32.
    It also adds the url filter as a version of what the uri filter used to do
    before we fixed it to do the right thing.

    Version 2.18 fixes a number of minor bugs. It also includes a modification to
    the parser grammar so that you can write expressions as arguments to
    subroutine, method or vmethod calls.

    Versions 2.17 and 2.16 were interim releases by Adam Kennedy who took care of
    some installation problems on Mac OSX while Andy was busy elsewhere.

    Version 2.15 is a major maintenance release.  It applies all outstanding
    patches and closes all open bugs listed on http://rt.cpan.org/  It
    includes:

     * XS Stash: enhancements include support for tied hashes/arrays
       and "fallback" methods on objects (e.g. accessing hash and
       list items and calling virtual methods)

     * Virtual Methods: added the scalar.remove, scalar.substr,
       hash.delete, hash.items, hash.pairs, list.import and list.hash
       virtual methods.  Added support for backreferences to
       scalar.replace and other improvements to list.push, list.unshift,
       list.hash, hash.list

     * Plugins: Added Math plugin, Bug fixes and enhancements to File,
       Image, URL and String plugins.  Moved DBI, XML and GD plugins
       into separate distributions.

     * Numerous other bug fixes, enhancements, documentation updates, all
       described in detail in the Changes file.

    More significant is what's not in version 2.15.  The DBI plugin has
    been moved into a separate Template-DBI distribution, the GD plugins
    into Template-GD, the XML plugins into Template-XML, and the Latex
    filters into Template-Latex.  This has been done in an effort to make
    the Template Toolkit core distribution smaller, cleaner and easier to
    configure and install.

    Version 2.14 added Unicode support to TT, a full set of command line
    options for tpage, the 'caller' and 'callers' items to each template
    component, some enhancements to the XML::Simple plugin, and a number
    of minor bug fixes.

    See the Changes file for further details of the changes in these and
    earlier releases.

    GENERAL FEATURES
    ----------------

    Some of the key features of the Template Toolkit are listed below.
    See the documentation for further detail.

      * simple but powerful template language

      * promotes a clear separation between application functionality and
        presentation elements

      * variable substitution allows binding to any Perl data types
        (scalars, hashes, lists, subs, objects)

      * conditional blocks (IF/UNLESS/ELSIF/ELSE, SWITCH/CASE)

      * loops and iterators (FOREACH, WHILE)

      * file/template inclusion (INSERT, INCLUDE, PROCESS, WRAPPER)

      * definition of local template components (BLOCK)

      * post-processing filters (FILTER)

      * plugin module architecture for easy extensibility (USE)

      * embedded Perl can be optionally enabled (PERL/RAWPERL)

      * full exception handling (TRY/THROW/CATCH/FINAL)

      * user-defined macros (MACRO)

      * definition of template metadata (META)

      * virtual methods for complex data types (e.g. list.size, hash.keys, etc.)

      * numerous configuration options

      * modular OO architecture allows extensive customisation

      * fast LALR(1) parser modules compiles templates according to a
        YACC-like grammar.

      * templates compiled to Perl code for efficient runtime execution

      * in-memory and on-disk caching of compiled templates

      * simple front end module (Template.pm) for ease of use

      * numerous plugin modules: CGI, DBI, XML, URL, Date, Table, etc

      * standard filters for html, case folding, regex search and replace, etc.

    DOCUMENTATION
    -------------

    The Template Toolkit is provided with enough documentation to keep all
    but the most voracious reader happy for quite some time.

    The 'Changes' file in the distribution directory documents all visible
    changes between versions of the Template Toolkit.  See the section
    'VERSION COMPATABILITY' below for further details.

    The 'TODO' file, also in the distribution directory, lists known bugs,
    planned enhancements and possible new features for future versions.

    The 'INSTALL' file covers the configuration and installation process.

    The rest of the documentation is distributed in Pod and HTML formats.
    The Pod pages are installed when you 'make install' and can be viewed
    using 'perldoc', e.g.

        perldoc Template

    If you're using a Unix based system then the pages should also be
    converted to manpages suring the 'make install'.  Thus, you can also:

        man Template

    (the man pages shouldn't have any problems relating to older versions)

    The HTML documentation and the means to rebuild it can be found in the
    'docs' sub-directory of the installation root.  If you opted to
    have it built at installation time, then there should be an 'html'
    directory within it containing the generated HTML built from the
    source templates.

    The documentation is now split into several sections.  The 'Template'
    page is now much shorter, containing information relating to the
    specifics of using the Template module, and a brief summary of
    everything else.  Information relating more generally to the Template
    Toolkit, features, syntax of the template language, plugins and so
    forth, has been split up into a number of Template::Manual::* pages.
    Template::Manual provides the index for the manual.

        perldoc Template::Manual

    Individual sections can be viewed as, for example,

        perldoc Template::Manual::Syntax
        perldoc Template::Manual::Directives
        perldoc Template::Manual::Plugins

    The Template::Tutorial provides an index to the tutorial documents.
    There are currently 2 tutorials, on generating web content, and on
    creating and using data files.

        perldoc Template::Tutorial
        perldoc Template::Tutorial::Web
        perldoc Template::Tutorial::Datafile

    The new template libraries distributed with the Template Toolkit have
    some documentation, but be warned that it is rather spartan at
    present.  If you're interested in using these libraries then the
    examples (in the 'examples' sub-directory) are likely to be much more
    useful until the documentation catches up.

        perldoc Template::Library::HTML
        perldoc Template::Library::Splash

    Each of the various modules that comprise the Template Toolkit has its
    own associated documention.  The 'Template::Modules' manpage lists
    these modules along with a brief description of their functions.

        perldoc Template::Modules

    See the individual pages for further detail:

        perldoc Template::Context
        perldoc Template::Parser
        perldoc Template::Provider

    If you're interested in the internals of the Template Toolkit and want
    to know more about how it all works, then you might like to have a look
    at the following:

        perldoc Template::Manual::Internals

    This document also contains important information for people wishing
    to hack on the Template Toolkit.

    The final bit of good news is that there is now a FAQ for the Template
    Toolkit.

        perldoc Template::FAQ

    It's now got a few question in it, and better still, some answers!
    Further contributions welcome.

    Most of the documentation is stable and reliable.  Where it's not then
    it's usually marked as such.  In particular, the documentation for the
    template libraries (Template::Library::*), the FAQ (Template::FAQ) and
    internals (Template::Internals) are all under construction.

    SUPPORT
    -------

    The Template Toolkit mailing list provides a forum for discussing
    issues relating to the use and abuse of the Template Toolkit.  There
    are a number of knowledgeable and helpful individuals who frequent the
    list (including the author) who can often offer help or suggestions.
    Please respect their time and patience by checking the documentation
    and/or mailing list archives before asking questions that may already
    have been answered.

    To subscribe to the mailing list, send an email to:

        templates-request@template-toolkit.org

    with the message 'subscribe' in the body.  You can also use the web
    interface to subscribe or browse the archives:

        http://www.template-toolkit.org/mailman/listinfo/templates

    A low-volume, moderated mailing list exists for announcements about new
    releases of the Template Toolkit and related products.  To subscribe, send
    an email to:

        templates-announce-request@template-toolkit.org

    with the message 'subscribe' in the body.  A web interface also exists
    for subscription and browsing the archives:

        http://www.template-toolkit.org/mailman/listinfo/templates-announce

    For information about commercial support and consultancy for the Template
    Toolkit, please contact the author.

    AUTHOR
    ------

    The Template Toolkit was written by Andy Wardley <abw@wardley.org> with
    the invaluable assistance and contributions from many other people.
    See Template::Manual::Credits for details.

    COPYRIGHT
    ---------

    Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.

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