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

                                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 INSTALL
    -------------

    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, see the sections below on CONFIGURATION, BUILDING
    AND TESTING, and INSTALLATION.

    PREREQUISITES
    -------------

    The Template Toolkit is written entirely in Perl and should run on any
    platform on which Perl is available.  It requires Perl 5.006 or later.

    The 'ttree' utility uses the AppConfig module (version 1.56 or above)
    for parsing command line options and configuration files.  It is
    available from CPAN:

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

    The Template Toolkit implements a "plugin" architecture which allow
    you to incorporate the functionality of virtually any Perl module into
    your templates.  A number of plugin modules are included with the
    distribution for adding extra functionality or interfacing to external
    CPAN modules.  You don't need to install any of these external modules
    unless you plan to use those particular plugins.  See Template::Plugins
    and Template::Manual::Plugins for further details.

    OBTAINING AND INSTALLING THE TEMPLATE TOOLKIT
    ---------------------------------------------

    The latest release version of the Template Toolkit can be downloaded
    from any CPAN site:

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

    Interim and development versions may also be available, along with
    other useful information, news, publications, mailing list archives,
    etc., from the Template Toolkit web site:

        http://www.template-toolkit.org/

    The Template Toolkit is distributed as a gzipped tar archive file:

        Template-Toolkit-<version>.tar.gz

    where <version> represents the current version number, e.g. 2.19.

    To install the Template Toolkit, unpack the distribution archive to
    create an installation directory.  Something like this:

        tar zxf Template-Toolkit-2.19.tar.gz
    or
        gunzip Template-Toolkit-2.19.tar.gz
        tar xf Template-Toolkit-2.19.tar

    You can then 'cd' into the directory created,

        cd Template-Toolkit-2.19

    and perform the usual Perl installation procedure:

        perl Makefile.PL
        make
        make test
        make install	    # may need root access

    The Makefile.PL performs various sanity checks and then prompts for a
    number of configuration items.  The following CONFIGURATION section
    covers this in greater detail.

    If you choose to install the optional components then you may need to
    perform some post-installation steps to ensure that the template
    libraries, HTML documentation and examples can be correctly viewed via
    your web browser.  The INSTALLATION section covers this.

    INSTALLING ON MICROSOFT WIN32 PLATFORMS
    ---------------------------------------

    The easiest way to install the Template Toolkit on a Win32 machine is
    using ActiveState's Perl Package Manager (ppm) and the pre-compiled
    packages built by Chris Winters.  For further details, see:

        http://openinteract.sourceforge.net/
        http://activestate.com/

    If you prefer, you can manually install the Template Toolkit on Win32
    systems by following the instructions in this installation guide.
    However, please note that you are likely to encounter problems using
    'make' and should instead download and use 'nmake' as a replacement.
    This is available from Microsoft's ftp site.

        ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe

    In this case, you should substitute 'nmake' for 'make' in all the
    instructions contained herein.

    CONFIGURATION
    -------------

    This section covers the configuration of the Template Toolkit via
    the Makefile.PL program.  If you've successfully run this and didn't
    have any problems answering any of the questions then you probably
    don't need to read this section.

    The Makefile.PL Perl program performs the module configuration and
    generates the Makefile which can then be used to build, test and
    install the Template Toolkit.

        perl Makefile.PL

    The Template Toolkit now boasts a high-speed implementation of
    Template::Stash written in XS.  You can choose to build this as
    an optional module for using explicitly as an alternative to
    the regular pure-perl stash module.  In additional, you can opt
    to use the XS Stash as the default, typically making the Template
    Toolkit run twice as fast!

    When prompted, answer 'y' or 'n' to build and optionally use
    the XS Stash module by default:

        Do you want to build the XS Stash module? [y]
        Do you want to use the XS Stash for all Templates? [n]

    In additional to the Perl modules and POD documentation installed in
    the usual way, the Template Toolkit distribution also contains a
    number of optional components.

      * Template libaries for basic HTML, Pod -> HTML, and PostScript

      * Splash! - a stylish HTML user interface template library / widget set

      * HTML documentation - distributed in template form for customisation

      * Stylesheet templates to generate docs as vanilla HTML or using Splash!

      * Examples - numerous examples of using the template libraries

    The Makefile.PL will prompt to ask if you want these components installed.

        Do you want to install these components? [y]

    If you answer 'y' then you will first be asked to specify an
    installation directory.  This directory should be separate from your
    Perl installation directories.  If your operating system is Unix or
    Win32 then you should be offered a reasonable default.  Suggestions
    welcome for the correct values on other platforms.

    Unix:

        Installation directory [/usr/local/tt2]

    Win32:

        Installation directory [C:/Program Files/Template Toolkit 2]

    The Splash! template library uses a number of very small images to
    build user interface components.  These will be installed (when you
    "make install") into the 'images' directory relative to the
    installation root specified above.  If you want to use the Splash!
    library then you'll need to copy this images directory, define an
    alias to it (e.g. in the httpd.conf) or create a symbolic link to it
    so that your web server can find and serve the images within.  The
    INSTALLATION section below gives further details about how you might
    go about doing that, but for now you just need to specify what URL
    you plan to use.

        URL base for TT2 images? [/tt2/images]

    If you're installing on a Windows machine then the default value
    will be based on the installation directory specified above.  This
    should allow you to browse the documentation and any other Splash!
    files you create, with the images being accessed in the browser via
    the filesystem.  e.g.

        URL base for TT2 images? [C:/Program Files/Template Toolkit 2/images]

    On other platforms, we assume you'll be delivering the images via a
    web server and the default will be '/tt2/images'.  Other typical
    values might be '/images/tt2', '/~yourid/tt2/images' or even something
    like 'http://www.yourhost.org/images/tt2'.  If you haven't got a clue
    then it's probably best to accept the default and worry about it later
    when you get to the INSTALLATION section.  If you don't plan to use
    the Splash! library then you don't need to worry about this at all.
    You can accept the default, or type in a silly message to bring some
    small amusement to an otherwise dull process.

    The modules comprising the Template Toolkit contain comprehensive POD
    documentation which can be browsed using 'perldoc' or 'man' (if your
    system supports it).  This is all installed as the regular Perl part
    of the Template Toolkit.

    The distribution also includes a set of source templates and style
    elements for generating the same documentation in HTML format.  These
    will be installed into the 'docs' directory relative to the
    installation root entered above.

    The HTML documentation can be built for you at "make install" time in
    a plain and simple HTML format or using the Splash! library.  You can
    see examples of these different styles and browse the documentation
    online at:

        http://www.template-toolkit.org/docs/

    To have the HTML documentation built as part of the installation
    process, answer 'y' to the question:

        Do you want to build the HTML documentation? [y]

    and then specify if you want it built using the vanilla HTML style
    (answer: 'n') or using the Splash! library (answer: 'y').  The latter
    comes highly recommended for those readers who enjoy a small dose of
    of gratuitous eye candy served with their web pages, but if you answer
    'y' and select Splash! then you'll have to ensure that the images URL
    specified above is properly set.

        Do you want to use the Splash! library? [y]

    If you prefer your pages clean and simple and/or can't be bothered
    messing around configuring image directories, then select 'n' to
    generate the plain document style.  This generates a "text-only" HTML
    version, entirely free of graphics and embellished with no more
    than textual navigatory links.

    If you do specify that you want to use the Splash! library then you
    will be prompted to select a colour scheme.

        Which Splash! colour scheme would you like to use to build the
        documentation?  Acceptable values are:

          Name     Colours
          -------------------------
          default  lilac/mauve
          aqua     aqua/marine
          blue     grey75/blue75
          green    grey75/green75
          grey     grey75/grey50
          red      grey75/red75

        Enter name of Splash scheme:  [default]

    You can see examples of these different colour schemes at the Template
    Toolkit web site, as above:

        http://www.template-toolkit.org/docs/

    See the README in the 'docs' directory for instructions on building the
    HTML documentation manually and/or customising the templates to your own
    requirements.

    The final optional component is a set of examples showing use of the
    HTML, Splash! and PostScript template libraries.  These are installed
    into the 'examples' directory under the installation root and can
    also be automatically built at "make install" time.

        Do you want to build the HTML example pages? [y]

    Note that the examples rely on using the Splash! library and there is
    no vanilla HTML version (currently) available.  The examples mainly
    focus on Splash! and other "advanced" HTML stuff so it probably wouldn't
    make much sense, anyway.  Note that the PostScript examples are far from
    complete (only just begun, in fact).

    BUILDING AND TESTING
    --------------------

    This section describes the "make" and "make test" commands which build
    and test the Template Toolkit.  If you ran these without incident,
    then you can probably skip this section.

    The 'make' command will build the Template Toolkit modules in the
    usual manner.

        make

    The 'make test' command runs the test scripts in the 't' subdirectory.

        make test

    You can set the TEST_VERBOSE flag when running 'make test' to see the
    results of the individual tests:

        make test TEST_VERBOSE=1

    INSTALLATION
    ------------

    This section describes the final installation of the Template Toolkit
    via the "make install" and covers any additional steps you may need to
    take if you opted to build the HTML documentation and/or examples.

    The 'make install' will install the modules and scripts on your
    system.  You may need administrator privileges to perform this task.
    Alternately you can can install the Template Toolkit to a local
    directory (see ExtUtils::MakeMaker for full details), e.g.

        perl Makefile.PL PREFIX=/home/abw/

    Don't forget to update your PERL5LIB environment variable if you do
    this, or add a line to your script to tell Perl where to find the files,
    e.g.

        use lib qw( /home/abw/lib/perl5/site_perl/5.6.0 );

    If you chose to install the optional components then these will be
    also be installed as part of the "make install" procedure.  They are
    installed into the separate Template Toolkit directory (independant of
    any Perl location) specified during the configuration process. Note
    that you must have the correct permissions required to create and/or
    write to this directory.  If you run the "make install" as root, or
    some other privileged user, then the directory will be created (if it
    doesn't already exist) and all the files installed into it will be
    owned by that user.

    If you want to use the Splash! template library then you will need to
    ensure that the images URL base you specified during the configuration
    correctly maps onto the 'images' subdirectory of the installation.  If
    you built the HTML documentation then you'll also want to make that
    available via your web server.

    If you're installing in a Win32 machine and accepted the default
    values above then you should already be able to browse the HTML
    documentation and examples via the browser and have it display
    correctly.  Otherwise, you'll need to tweak the web server
    configuration, create links to the files or copy them to where the web
    server can find them.

    If you're using Apache then you might do something like this in the
    httpd.conf (in the <IfModule mod_alias.c> section, and here assumes
    /usr/local/tt2 is installation root)

        Alias /tt2/images/   /usr/local/tt2/images/
        Alias /tt2/docs/     /usr/local/tt2/docs/html/
        Alias /tt2/examples/ /usr/local/tt2/examples/html/

        <Directory /usr/local/tt2/>
            Options Indexes
            AllowOverride None
            Order allow,deny
            Allow from all
        </Directory>

    Another approach is to create a 'tt2' directory in your document root
    and create symbolic links to the relevant installation directories.  On a
    Unix system, it might be performed something like this:

        cd /path/to/your/webserver/docroot
        mkdir tt2
        cd tt2
        ln -s /usr/local/tt2/images images
        ln -s /usr/local/tt2/docs/html docs
        ln -s /usr/local/tt2/examples/html examples

    Note that if you use symbolic links, you'll have to make sure that you
    web server is configured to follow them.  For example, in Apache:

        <Location /tt2>
    	Options Indexes FollowSymLinks
        </Location>

    You should then be able to access the Template Toolkit documentation
    as:

        http://www.yourserver.org/tt2/docs/

    and examples as:

        http://www.yourserver.org/tt2/examples/

    If you haven't got configuration access to your webserver or don't
    want to go messing with it, then you can always copy everything to a
    user directory (or create links to it if your webserver is configured
    to follow them from your user directory).  e.g.

        mkdir ~/public_html/tt2
        cd ~/public_html/tt2
        cp -R /usr/local/tt2/images .
        cp -R /usr/local/tt2/docs/html docs
        cp -R /usr/local/tt2/example/html examples

    You should then be able to access them as (for example):

        http://www.yourserver.org/~yourid/tt2/docs/
        http://www.yourserver.org/~yourid/tt2/examples/

    And of course, the value for the base URL of the Template Toolkit images
    (as specified in the configuration process) should be something like:

        /~yourid/tt2/images

    The examples and HTML docs (if you built them with Splash!) will
    reference the Splash! images using this URL (default: '/tt2/images').
    If this value is incorrect then instead of smooth, rounded corners,
    the user interface components will have broken images links, square
    blocks of colour, or other ghastly abberations dotted across them.

    If necessary, you can re-install the Template Toolkit to specify a
    different image URL.  Alternately, you can fix the value in the
    'templates/splash/config' file (under the installation directory)
    and rebuild the documentation and/or examples.

    The Makefile generated by Makefile.PL contains 4 additional targets:
    tt2_install, tt2_splash, tt2_html_docs and tt2_examples (but only if
    you selected the appropriate options).  These are run automatically as
    part of the "make install" (you can do "make pure_install" or "make
    doc_install" instead of "make install" to just get the Perl module or
    regular documentation installation by itself).  You can also run them
    manually if you want to re-install the additional components, generate
    the Splash! images, rebuild the documentation or the examples at some
    later date:

        make tt2_install
        make tt2_splash
        make tt2_html_docs
        make tt2_examples

    The README files in the 'docs' and 'examples' directories contain
    futher information about rebuilding HTML and examples if you want to
    dig deeper.

    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.