[Templates-svn] r1087 - in trunk/lib/Template: . Manual Namespace
svn@template-toolkit.org
svn@template-toolkit.org
Author: abw
Date: 2007-05-29 14:37:02 +0100 (Tue, 29 May 2007)
New Revision: 1087
Modified:
trunk/lib/Template/Manual.pod
trunk/lib/Template/Manual/Intro.pod
trunk/lib/Template/Manual/Plugins.pod
trunk/lib/Template/Modules.pod
trunk/lib/Template/Namespace/Constants.pm
trunk/lib/Template/Toolkit.pod
trunk/lib/Template/Tools.pod
trunk/lib/Template/Tutorial.pod
Log:
cleaned up some more docs, including Template::Toolkit and other section indexes: Template::Tools, Template::Modules, etc
Modified: trunk/lib/Template/Manual/Intro.pod
===================================================================
--- trunk/lib/Template/Manual/Intro.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Manual/Intro.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -21,7 +21,7 @@
The Template Toolkit is a collection of Perl modules which implement a
fast, flexible, powerful and extensible template processing system.
-It is primarily used for generating dynamic web content, although it can
+It is most often used for generating dynamic web content, although it can
be used equally well for processing any kind of text documents.
At the simplest level it provides an easy way to process template
Modified: trunk/lib/Template/Manual/Plugins.pod
===================================================================
--- trunk/lib/Template/Manual/Plugins.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Manual/Plugins.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -169,7 +169,7 @@
=head2 GD
The C<GD> plugins are no longer part of the core Template Toolkit distribution.
-They are now available in a separate L<Template::GD|Template-GD> distribution.
+They are now available in a separate L<Template-GD|Template-GD> distribution.
=head2 HTML
@@ -276,7 +276,7 @@
The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no
longer distributed with the Template Toolkit as of version 2.15
-They are now available in a separate L<Template::XML|Template-XML> distribution.
+They are now available in a separate L<Template-XML|Template-XML> distribution.
=cut
Modified: trunk/lib/Template/Manual.pod
===================================================================
--- trunk/lib/Template/Manual.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Manual.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -16,6 +16,10 @@
#
#========================================================================
+=head1 NAME
+
+Template::Manual - Template Toolkit User Manual
+
=head1 Template Toolkit Manual
The Template Toolkit manual contains documentation on using and extending
Modified: trunk/lib/Template/Modules.pod
===================================================================
--- trunk/lib/Template/Modules.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Modules.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -15,6 +15,10 @@
#
#========================================================================
+=head1 NAME
+
+Template::Modules - Template Toolkit Modules
+
=head1 Template Toolkit Modules
This documentation provides an overview of the different modules that
Modified: trunk/lib/Template/Namespace/Constants.pm
===================================================================
--- trunk/lib/Template/Namespace/Constants.pm 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Namespace/Constants.pm 2007-05-29 13:37:02 UTC (rev 1087)
@@ -10,15 +10,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Namespace::Constants;
@@ -37,7 +33,7 @@
sub _init {
my ($self, $config) = @_;
$self->{ STASH } = Template::Config->stash($config)
- || return $self->error(Template::Config->error());
+ || return $self->error(Template::Config->error());
return $self;
}
@@ -61,33 +57,33 @@
print STDERR "constant ident [ @$ident ] " if $DEBUG;
foreach $e (0..$nelems-1) {
- # node name must be a constant
- unless ($ident->[$e * 2] =~ s/^'(.+)'$/$1/s) {
- $self->DEBUG(" * deferred (non-constant item: ", $ident->[$e * 2], ")\n")
- if $DEBUG;
- return Template::Directive->ident(\@save);
- }
+ # node name must be a constant
+ unless ($ident->[$e * 2] =~ s/^'(.+)'$/$1/s) {
+ $self->DEBUG(" * deferred (non-constant item: ", $ident->[$e * 2], ")\n")
+ if $DEBUG;
+ return Template::Directive->ident(\@save);
+ }
- # if args is non-zero then it must be eval'ed
- if ($ident->[$e * 2 + 1]) {
- my $args = $ident->[$e * 2 + 1];
- my $comp = eval "$args";
- if ($@) {
- $self->DEBUG(" * deferred (non-constant args: $args)\n") if $DEBUG;
- return Template::Directive->ident(\@save);
- }
- $self->DEBUG("($args) ") if $comp && $DEBUG;
- $ident->[$e * 2 + 1] = $comp;
- }
+ # if args is non-zero then it must be eval'ed
+ if ($ident->[$e * 2 + 1]) {
+ my $args = $ident->[$e * 2 + 1];
+ my $comp = eval "$args";
+ if ($@) {
+ $self->DEBUG(" * deferred (non-constant args: $args)\n") if $DEBUG;
+ return Template::Directive->ident(\@save);
+ }
+ $self->DEBUG("($args) ") if $comp && $DEBUG;
+ $ident->[$e * 2 + 1] = $comp;
+ }
}
$result = $self->{ STASH }->get($ident);
if (! length $result || ref $result) {
- my $reason = length $result ? 'reference' : 'no result';
- $self->DEBUG(" * deferred ($reason)\n") if $DEBUG;
- return Template::Directive->ident(\@save);
+ my $reason = length $result ? 'reference' : 'no result';
+ $self->DEBUG(" * deferred ($reason)\n") if $DEBUG;
+ return Template::Directive->ident(\@save);
}
$result =~ s/'/\\'/g;
@@ -101,18 +97,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Namespace::Constants - Compile time constant folding
@@ -121,33 +105,33 @@
# easy way to define constants
use Template;
-
+
my $tt = Template->new({
- CONSTANTS => {
- pi => 3.14,
- e => 2.718,
- },
+ CONSTANTS => {
+ pi => 3.14,
+ e => 2.718,
+ },
});
# nitty-gritty, hands-dirty way
use Template::Namespace::Constants;
-
+
my $tt = Template->new({
- NAMESPACE => {
- constants => Template::Namespace::Constants->new({
- pi => 3.14,
- e => 2.718,
+ NAMESPACE => {
+ constants => Template::Namespace::Constants->new({
+ pi => 3.14,
+ e => 2.718,
},
- },
+ },
});
=head1 DESCRIPTION
-The Template::Namespace::Constants module implements a namespace handler
-which is plugged into the Template::Directive compiler module. This then
+The C<Template::Namespace::Constants> module implements a namespace handler
+which is plugged into the C<Template::Directive> compiler module. This then
performs compile time constant folding of variables in a particular namespace.
-=head1 PUBLIC METHODS
+=head1 METHODS
=head2 new(\%constants)
@@ -156,8 +140,8 @@
to store the constant variable definitions passed as arguments.
my $handler = Template::Namespace::Constants->new({
- pi => 3.14,
- e => 2.718,
+ pi => 3.14,
+ e => 2.718,
});
=head2 ident(\@ident)
@@ -170,27 +154,18 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-1.27, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template::Directive|Template::Directive>
+L<Template::Directive>
=cut
Modified: trunk/lib/Template/Toolkit.pod
===================================================================
--- trunk/lib/Template/Toolkit.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Toolkit.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -18,77 +18,112 @@
=head1 NAME
-Template::Toolkit - Template processing system
+Template::Toolkit - Template Processing System
-=head1 SYNOPSIS
+=head1 Introduction
- $ perldoc Template # docs for the Template Perl module
+The Template Toolkit is a collection of Perl modules which implement a
+fast, flexible, powerful and extensible template processing system.
- $ perldoc Template::Manual # Template Toolkit manual
+It is "input-agnostic" and can be used equally well for processing any
+kind of text documents: HTML, XML, CSS, Javascript, Perl code, plain text,
+and so on. However, it is most often used for generating static and
+dynamic web content, so that's what we'll focus on here.
-=head1 DESCRIPTION
+Although the Template Toolkit is written in Perl, you don't need to be a Perl
+programmer to use it. It was designed to allow non-programmers to easily
+create and maintain template-based web sites without having to mess around
+writing Perl code or going crazy with cut-n-paste.
-The Template Toolkit is a collection of Perl modules which implement a
-fast, flexible, powerful and extensible template processing system.
+However, the Template Toolkit is also designed to be extremely flexible and
+extensible. If you are a Perl programmer, or know someone who is, then you can
+easily hook the Template Toolkit into your existing code, data, databases and
+web applications. Furthermore, you can easily extend the Template Toolkit
+through the use of its plugin mechanism and other developer APIs.
-It was originally designed and remains primarily useful for generating
-dynamic web content. Howver it can be used equally well for
-processing any other kind of text based documents including HTML, XML,
-POD, PostScript, LaTeX and plain old text.
+Whatever context you use it in, the primary purpose of the Template Toolkit is
+to allow you to create a clear separation between the presentation elements of
+your web site and everything else.
-The L<Template::Manual> documentation contains further information about
-the Template Toolkit and a full reference of all the features,
-directives, configuration options and so on.
+If you're generating static web pages, then you can use it to separate the
+commonly repeated user interface elements on each page (headers, menus,
+footers, etc.) from the core content. If you're generating dynamic web pages
+for the front end of a web application, then you'll also be using it to keep
+the back-end Perl code entirely separate from the front-end HTML templates.
+Either way, a I<clear separation of concerns> is what allow you to
+concentrate on one thing at a time without the other things getting in your
+way. And that's what the Template Toolkit is all about.
- $ perldoc Template::Manual
+=head1 Documentation
-The L<Template> module is the front-end to the Template Toolkit for Perl
-programmers. The documentation for that module relates specifically
-to using the module from Perl programs.
+The documentation for the Template Toolkit is organised into four sections.
- $ perldoc Template
+The L<Template::Manual> contains detailed information about using the Template
+Toolkit. It gives examples of its use and includes a full reference of the
+template language, configuration options, filters, plugins and other component
+parts.
-Please note that there is no L<Template::Toolkit> Perl module, just this
-documentation pointing people to the right place.
+The L<Template::Modules> page lists the Perl modules that comprise the
+Template Toolkit. It gives a brief explanation of what each of them does, and
+provides a link to the complete documentation for each module for further
+information. If you're a Perl programmer looking to use the Template Toolkit
+from your Perl programs then this section is likely to be of interest.
-You're welcome to refer to TT as "Template Toolkit" or
-"Template::Toolkit" if you prefer. The official line is that we talk
-about the "Template Toolkit" software and the "Template" Perl module.
-But we're not the kind of officials who would get all official on you.
+Most, if not all of the information you need to call the Template Toolkit from
+Perl is in the documentation for the L<Template> module. You only really need
+to start thinking about the other modules if you want to extend or modify the
+Template Toolkit in some way, or if you're interested in looking under the
+hood to see how it all works.
-You don't need to be a Perl programmer to use the Template Toolkit.
-The L<Template::Tools::tpage|tpage> and L<Template::Tools::ttree|ttree>
-scripts allow you to process templates from the command line.
-See the documentation for those scripts for further information.
+The documentation for each module is embedded as POD in each
+module, so you can always use C<perldoc> from the command line to read a
+module's documentation. e.g.
- $ perldoc tpage
- $ perldoc ttree
+ $ perldoc Template
+ $ perldoc Template::Context
+ ...etc...
-Finally, don't forget to check out the Template Toolkit web site.
+It's worth noting that all the other documentation, including the user manual
+is available as POD. e.g.
- L<http://template-toolkit.org/>
+ $ perldoc Template::Manual
+ $ perldoc Template::Manual::Config
+ ...etc...
-Yes, we know it doesn't look very pretty and should use CSS instead of
-tables for layout. We'll have a shiny new web site when TT3 is
-released. In case you're wondering, that'll be on Tuesday some time
-shortly after lunch...
+The L<Template::Tools> section contains the documentation for
+L<Template::Tools::tpage|tpage> and L<Template::Tools::ttree|ttree>.
+These are two command line programs that are distributed with the
+Template Toolkit. L<tpage|Template::Tools::tpage> is used to process
+a single template file, L<ttree|Template::Tools::ttree> for processing
+entire directories of template files.
-=head1 AUTHOR
+The L<Template::Tutorial> section contains two introductory tutorials on using
+the Template Toolkit. The first is L<Template::Tutorial::Web> on generating
+web content. The second is L<Template::Tutorial::Datafile> on using the
+Template Toolkit to generate other data formats including XML.
-Andy Wardley E<lt>abw@wardley.orgE<gt>
+All of the documentation is also provided in HTML format in the
+F<docs> sub-directory of the Template Toolkit distribution. You can
+also read it online at the Template Toolkit web site:
+L<http://template-toolkit.org/>
-L<http://wardley.org/>
+=head1 Author
-=head1 COPYRIGHT
+The Template Toolkit was written by L<Andy Wardley|http://wardley.org/>
+E<lt>abw@wardley.orgE<gt> with assistance and contributions from a great
+number of people. Please see L<Template::Manual::Credits> for a full list.
+=head1 Copyright
+
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
-=head1 SEE ALSO
+=head1 See Also
-L<Template>, L<Template::Manual>
+L<Template>, L<Template::Manual>, L<Template::Modules>, L<Template::Tools>,
+L<Template::Tutorial>
=cut
Modified: trunk/lib/Template/Tools.pod
===================================================================
--- trunk/lib/Template/Tools.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Tools.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -17,6 +17,10 @@
#
#========================================================================
+=head1 NAME
+
+Template::Tools - Command Line Tools for the Template Toolkit
+
=head1 Template Tools
The Template Toolkit includes the following command line tools
Modified: trunk/lib/Template/Tutorial.pod
===================================================================
--- trunk/lib/Template/Tutorial.pod 2007-05-27 17:36:15 UTC (rev 1086)
+++ trunk/lib/Template/Tutorial.pod 2007-05-29 13:37:02 UTC (rev 1087)
@@ -16,6 +16,10 @@
#
#========================================================================
+=head1 NAME
+
+Template::Tutorial - Template Toolkit Tutorials
+
=head1 Template Toolkit Tutorials
=head2 Template::Tutorial::Web