[Templates-cvs] cvs commit: Template2/docs/src/Modules/Template/Stash Context.html XS.html
cvs@template-toolkit.org
cvs@template-toolkit.org
cvs 06/05/26 13:44:55
Modified: docs/src/Modules/Template/Stash Context.html XS.html
Log:
Version 2.15
Revision Changes Path
1.37 +5 -5 Template2/docs/src/Modules/Template/Stash/Context.html
Index: Context.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Modules/Template/Stash/Context.html,v
retrieving revision 1.36
retrieving revision 1.37
diff -u -r1.36 -r1.37
--- Context.html 2006/01/30 20:03:49 1.36
+++ Context.html 2006/05/26 13:44:55 1.37
@@ -107,22 +107,22 @@
[% WRAPPER section
title="AUTHOR"
-%]<p>
-Andy Wardley <abw@andywardley.com>
+Andy Wardley <abw@wardley.org>
</p>
<p>
-[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
+[% ttlink('http://wardley.org/', 'http://wardley.org/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
-1.59, distributed as part of the
-Template Toolkit version 2.15, released on 30 January 2006.
+1.60, distributed as part of the
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
1.31 +33 -64 Template2/docs/src/Modules/Template/Stash/XS.html
Index: XS.html
===================================================================
RCS file: /template-toolkit/Template2/docs/src/Modules/Template/Stash/XS.html,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -r1.30 -r1.31
--- XS.html 2006/01/30 20:03:49 1.30
+++ XS.html 2006/05/26 13:44:55 1.31
@@ -19,9 +19,6 @@
title ="DESCRIPTION"
subs = [];
PROCESS tocitem
- title ="NOTE"
- subs = [];
- PROCESS tocitem
title ="BUGS"
subs = [];
PROCESS tocitem
@@ -49,46 +46,50 @@
[% WRAPPER section
title="DESCRIPTION"
-%]<p>
-This module loads the XS version of Template::Stash::XS. It should
-behave very much like the old one, but run about twice as fast.
-See the synopsis above for usage information.
+The Template:Stash::XS module is an implementation of the
+Template::Stash written in C. The "XS" in the name refers to Perl's
+XS extension system for interfacing Perl to C code. It works just
+like the regular Perl implementation of Template::Stash but runs about
+twice as fast.
</p>
<p>
-Only a few methods (such as get and set) have been implemented in XS.
-The others are inherited from Template::Stash.
-</p>
-[%- END %]
-[% WRAPPER section
- title="NOTE"
--%]<p>
-To always use the XS version of Stash, modify the Template/Config.pm
-module near line 45:
+The easiest way to use the XS stash is to configure the Template
+Toolkit to use it by default. You can do this at installation time
+(when you run <code>'perl Makefile.PL'</code>) by answering 'y' to the questions:
</p>
-<pre> $STASH = 'Template::Stash::XS';</pre>
+<pre> Do you want to build the XS Stash module? y
+ Do you want to use the XS Stash by default? y</pre>
<p>
-If you make this change, then there is no need to explicitly create
-an instance of Template::Stash::XS as seen in the SYNOPSIS above. Just
-use Template as normal.
+See the <file>INSTALL</file> file distributed with the Template Toolkit for further
+details on installation.
</p>
<p>
-Alternatively, in your code add this line before creating a Template
-object:
+If you don't elect to use the XS stash by default then you should use
+the <code>'STASH'</code> configuration item when you create a new Template object.
+This should reference an XS stash object that you have created
+manually.
</p>
-<pre> $Template::Config::STASH = 'Template::Stash::XS';</pre>
+<pre> use Template;
+ use Template::Stash::XS;</pre>
+<pre> my $stash = Template::Stash::XS->new(\%vars);
+ my $tt2 = Template->new({ STASH => $stash });</pre>
<p>
-To use the original, pure-perl version restore this line in
-Template/Config.pm:
+Alternately, you can set the <code>'$Template::Config::STASH'</code> package
+variable like so:
</p>
-<pre> $STASH = 'Template::Stash';</pre>
+<pre> use Template;
+ use Template::Config;</pre>
+<pre> $Template::Config::STASH = 'Template::Stash::XS';</pre>
+<pre> my $tt2 = Template->new();</pre>
<p>
-Or in your code:
+The XS stash will then be automatically used.
</p>
-<pre> $Template::Config::STASH = 'Template::Stash';</pre>
<p>
-You can elect to have this performed once for you at installation
-time by answering 'y' or 'n' to the question that asks if you want
-to make the XS Stash the default.
+If you want to use the XS stash by default and don't want to
+re-install the Template Toolkit, then you can manually modify the
+<code>'Template/Config.pm'</code> module near line 42 to read:
</p>
+<pre> $STASH = 'Template::Stash::XS';</pre>
[%- END %]
[% WRAPPER section
title="BUGS"
@@ -96,38 +97,6 @@
Please report bugs to the Template Toolkit mailing list
templates@template-toolkit.org
</p>
-<p>
-As of version 2.05 of the Template Toolkit, use of the XS Stash is
-known to have 2 potentially troublesome side effects. The first
-problem is that accesses to tied hashes (e.g. Apache::Session) may not
-work as expected. This should be fixed in an imminent release. If
-you are using tied hashes then it is suggested that you use the
-regular Stash by default, or write a thin wrapper around your tied
-hashes to enable the XS Stash to access items via regular method
-calls.
-</p>
-<p>
-The second potential problem is that enabling the XS Stash causes all
-the Template Toolkit modules to be installed in an architecture
-dependant library, e.g. in
-</p>
-<pre> /usr/lib/perl5/site_perl/5.6.0/i386-linux/Template</pre>
-<p>
-instead of
-</p>
-<pre> /usr/lib/perl5/site_perl/5.6.0/Template</pre>
-<p>
-At the time of writing, we're not sure why this is happening but it's
-likely that this is either a bug or intentional feature in the Perl
-ExtUtils::MakeMaker module. As far as I know, Perl always checks the
-architecture dependant directories before the architecture independant
-ones. Therefore, a newer version of the Template Toolkit installed
-with the XS Stash enabled should be used by Perl in preference to any
-existing version using the regular stash. However, if you install a
-future version of the Template Toolkit with the XS Stash disabled, you
-may find that Perl continues to use the older version with XS Stash
-enabled in preference.
-</p>
[%- END %]
[% WRAPPER section
title="AUTHORS"
@@ -141,12 +110,12 @@
[% WRAPPER section
title="VERSION"
-%]<p>
-Template Toolkit version 2.15, released on 30 January 2006.
+Template Toolkit version 2.15, released on 26 May 2006.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
--%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
+-%]<pre> Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or