Provided by: libpetal-perl_2.23-1_all bug

NAME

       Petal - Perl Template Attribute Language - TAL for Perl!

SYNOPSIS

       in your Perl code:

         use Petal;
         my $template = new Petal ('foo.xhtml');
         print $template->process (bar => 'BAZ');

       in foo.xhtml

         <html xmlns:tal="http://purl.org/petal/1.0/">
           <body tal:content="bar">Dummy Content</body>
         </html>

       and you get something like:

         <html>
           <body>BAZ</body>
         </html>

SUMMARY

       Petal is a XML based templating engine that is able to process any kind of XML, XHTML and
       HTML.

       Petal borrows a lot of good ideas from the Zope Page Templates TAL specification, it is
       very well suited for the creation of WYSIWYG XHTML editable templates.

       The idea is to further enforce the separation of logic from presentation. With Petal,
       graphic designers can use their favorite WYSIWYG editor to easily edit templates without
       having to worry about the loops and ifs which happen behind the scene.

NAMESPACE

       Although this is not mandatory, Petal templates should include use the namespace
       <http://purl.org/petal/1.0/>. Example:

           <html xml:lang="en"
                 lang="en"
                 xmlns="http://www.w3.org/1999/xhtml"
                 xmlns:tal="http://purl.org/petal/1.0/">

             Blah blah blah...
             Content of the file
             More blah blah...
           </html>

       If you do not specify the namespace, Petal will by default try to use the "petal:" prefix.
       However, in all the examples of this POD we'll use the "tal:" prefix to avoid too much
       typing.

KICKSTART

       Let's say you have the following Perl code:

           use Petal;
           local $Petal::OUTPUT = 'XHTML';

           my $template = new Petal ('foo.xhtml');
           $template->process ( my_var => some_object() );

       some_object() is a subroutine that returns some kind of object, may it be a scalar,
       object, array referebce or hash reference. Let's see what we can do...

   Version 1: WYSIWYG friendly prototype.
       Using TAL you can do:

           This is the variable 'my_var' :
           <span tal:replace="my_var/hello_world">Hola, Mundo!</span>

       Now you can open your template in any WYSIWYG tool (mozilla composer, frontpage,
       dreamweaver, adobe golive...) and work with less risk of damaging your petal commands.

   Version 2: Object-oriented version
       Let's now say that "my_var" is actually an object with a method hello_world() that returns
       Hello World. To output the same result, your line, which was:

           <span tal:replace="my_var/hello_world">Hola, Mundo!</span>

       Would need to be... EXACTLY the same. Petal lets you access hashes and objects in an
       entirely transparent way and tries to automagically do The Right Thing for you.

       This high level of polymorphism means that in most cases you can maintain your code, swap
       hashes for objects, and not change a single line of your template code.

   Version 3: Personalizable
       Now let's say that your method hello_world() can take an optional argument so that
       "$some_object->hello_world ('Jack')" returns Hello Jack.

       You would write:

           <span tal:replace="my_var/hello_world 'Jack'">Hola, Mundo!</span>

       Optionally, you can get rid of the quotes by using two dashes, a la GNU command-line
       option:

           <span tal:replace="my_var/hello_world --Jack">Hola, Mundo!</span>

       So you can pass parameters to methods using double dashes or quotes.  Now let us say that
       your "my_var" object also has a method current_user() that returns the current user real
       name. You can do:

           <span tal:replace="my_var/hello_world my_var/current_user">Hola, Mundo!</span>

       TRAP:

       You cannot write nested expressions such as:

           ${my_var/hello_world ${my_var/current_user}}

       This will NOT work. At least, not yet.

   Version 4: Internationalized
       Let's say that you have a directory called "hello_world" with the following files:

           hello_world/en.xhtml
           hello_world/fr.xhtml
           hello_world/es.xhtml

       You can use Petal as follows in your Perl code:

           use Petal;
           local $Petal::OUTPUT = 'XHTML';

           my $template = new Petal ( file => 'hello_world', lang => 'fr-CA' );
           print $template->process ( my_var => some_object() );

       What will happen is that the $template object will look in the "hello_world" directory and
       try to find a file named "fr-CA.xhtml", then "fr.xhtml", then will default to "en.xhtml".
       It works fine for includes, too!

       These internationalized templates can have whatever file-extension you like, Petal
       searches on the first part of the filename.  So you can call them "fr.html", "fr.xml",
       "fr.xhtml" or use whatever convention suits you.

       NOTE: There is now support for ZPT-like i18n attributes, which should provide a much nicer
       framework. See Petal::I18N for details.

       TIP:

       If you feel that 'en' should not be the default language, you can specify a different
       default:

           my $template = new Petal (
               file             => 'hello_world',
               language         => 'zh',
               default_language => 'fr' # vive la France!
           );

       TRAP:

       If you do specify the "lang" option, you MUST use a path to a template directory, not a
       file directory.

       Conversely, if you do not specify a "lang" option, you MUST use a path to a template file,
       not a directory.

OPTIONS

       When you create a Petal template object you can specify various options using name =>
       value pairs as arguments to the constructor.  For example:

         my $template = Petal->new(
           file     => 'gerbils.html',
           base_dir => '/var/www/petshop',
           input    => 'HTML',
           output   => 'HTML',
         );

       The recognized options are:

   file => filename
       The template filename.  This option is mandatory and has no default.

       Note: If you also use 'language' this option should point to a directory.

   base_dir => pathname | [ pathname list ] (default: '.')
       The directories listed in this option will be searched in turn to locate the template
       file.  A single directory can be specified as a scalar.  For a directory list use an
       arrayref.

   input => 'HTML' | 'XHTML' | 'XML' (default: 'XML')
       Defines the format of the template files.  Recognised values are:

         'HTML'  - Alias for 'XHTML'
         'XHTML' - Petal will use Petal::Parser to parse the template
         'XML'   - Petal will use Petal::Parser to parse the template

   output => 'HTML' | 'XHTML' | 'XML' (default: 'XML')
       Defines the format of the data generated as a result of processing the template files.
       Recognised values are:

         'HTML'  - Petal will output XHTML, self-closing certain tags
         'XHTML' - Alias for 'HTML'
         'XML'   - Petal will output generic XML

   language => language code
       For internationalized applications, you can use the 'file' option to point to a directory
       and select a language-specific template within that directory using the 'language' option.
       Languages are selected using a two letter code (eg: 'fr') optionally followed by a hyphen
       and a two letter country code (eg: 'fr-CA').

   default_language => language code (default: 'en')
       This language code will be used if no template matches the selected language-country or
       language.

   taint => true | false (default: false)
       If set to "true", makes perl taint mode happy.

   error_on_undef_var => true | false (default: true)
       If set to "true", Petal will confess() errors when trying to access undefined template
       variables, otherwise an empty string will be returned.

   disk_cache => true | false (default: true)
       If set to "false", Petal will not use the "Petal::Cache::Disk" module.

   memory_cache => true | false (default: true)
       If set to "false", Petal will not use the "Petal::Cache::Memory" module.

   cache_only => true | false (default: false)
       If set to "true", Petal will return true after having compiled a template into perl code
       and a subroutine , and optionally using disk_cache or memory_cache if either is set.

   max_includes => number (default: 30)
       The maximum number of recursive includes before Petal stops processing.  This is to guard
       against accidental infinite recursions.

   debug_dump => true | false (default: true)
       If this option is true, when Petal cannot process a template it will output lots of
       debugging information in a temporary file which you can inspect.  The location for this
       file is wherever File::Spec->tmpdir() specifies as a temp directory (usually /tmp on a
       unix system).

   encode_charset => charset (default: undef)
       This option is _DEPRECATED_ as of Petal 2.01.  Petal will now always return results in
       Perl's internal form.

       It doesn't guarantee that the result will be in UTF-8 or in your local encoding, but at
       least the UTF-8 flag should be set properly.

       If you want to encode the results for a specific charset, you should look at the module
       Encode.

   decode_charset => charset (default: undef)
       This option will work only if you use Perl 5.8 or greater.

       If specified, Petal will assume that the template to be processed (and its sub-templates)
       are in the character set charset.

       charset can be any character set that can be used with the module Encode.

TAL SYNTAX

       This functionality is directly and shamelessly stolen from the excellent TAL
       specification: <http://wiki.zope.org/ZPT/TAL>.

   define
       Abstract

         <tag tal:define="variable_name EXPRESSION">

       Evaluates "EXPRESSION" and assigns the returned value to "variable_name".

       Example

         <!--? sets document/title to 'title' -->
         <span tal:define="title document/title">

       Why?

       This can be useful if you have a "very/very/long/expression".  You can set it to let's say
       "vvle" and then use "vvle" instead of using "very/very/long/expression".

   condition (ifs)
       Abstract

         <tag tal:condition="true:EXPRESSION">
            blah blah blah
         </tag>

       Example

         <span tal:condition="true:user/is_authenticated">
           Yo, authenticated!
         </span>

       Why?

       Conditions can be used to display something if an expression is true. They can also be
       used to check that a list exists before attempting to loop through it.

   repeat (loops)
       Abstract

         <tag tal:repeat="element_name EXPRESSION">
            blah blah blah
         </tag>

       Why?

       Repeat statements are used to loop through a list of values, typically to display the
       resulting records of a database query.

       Example:

         <li tal:repeat="user system/user_list">$user/real_name</li>

       A select list with one item selected:

         <select>
           <option
             selected="selected"
             tal:attributes="value self/selected_lang/value"
             tal:content="self/selected_lang/label"
           >English</option>
           <option
             value="i-klingon"
             tal:repeat="lang self/unselected_langs;"
             tal:attributes="value lang/value"
             tal:content="lang/label"
           >Klingon</option>
         </select>

       A table with rows of alternating colours set via CSS:

         <table>
           <div
             tal:omit-tag=""
             tal:repeat="audience self/audiences"
           >
             <tr
               class="odd"
               tal:condition="repeat/odd"
             >
               <td>
                 This a odd row, it comes before the even row.
               </td>
             </tr>
             <tr
               class="even"
               tal:condition="repeat/even"
             >
               <td>
                 This a even row.
               </td>
             </tr>
           </div>
         </table>

       repeat is a local temporary object that only exists within a petal:repeat loop.  It has a
       bunch of methods useful for selecting different positions in the loop:

       repeat/index

       index returns the numeric position of this item within the loop, starts with one not zero.

       repeat/number

       number is an alias for index.

       repeat/even

       even is true if the position is even (0, 2, 4 ...)

       repeat/odd

       odd is true is the position is odd (1, 3, 5 ...)

       repeat/start

       start is true if this is the first item.

       repeat/end

       end is true if this is the last item.

       repeat/inner

       inner is true if this is not the start or end.

   attributes
       Abstract

         <tag tal:attributes="attr1 EXPRESSION_1; attr2 EXPRESSION_2"; ...">
            blah blah blah
         </tag>

       Example

         <a href="http://www.gianthard.com"
            lang="en-gb"
            tal:attributes="href document/href_relative; lang document/lang">

       Why?

       Attributes statements can be used to template a tag's attributes.

   content
       Abstract

         <tag tal:content="EXPRESSION">Dummy Data To Replace With EXPRESSION</tag>

       By default, the characters greater than, lesser than, double quote and ampersand are
       encoded to the entities &lt;, &gt;, &quot; and &amp; respectively.  If you don't want them
       to (because the result of your expression is already encoded) you have to use the
       "structure" keyword.

       Example

         <span tal:content="title">Dummy Title</span>

         <span tal:content="structure some/variable">
            blah blah blah
         </span>

       Why?

       It lets you replace the contents of a tag with whatever value the evaluation of EXPRESSION
       returned. This is handy because you can fill your templates with dummy content which will
       make them usable in a WYSIWYG tool.

   replace
       Abstract

         <tag tal:replace="EXPRESSION">
           This time the entire tag is replaced
           rather than just the content!
         </tag>

       Example

         <span tal:replace="title">Dummy Title</span>

       Why?

       Similar reasons to "content". Note however that "tal:content" and "tal:replace" are *NOT*
       aliases. The former will replace the contents of the tag, while the latter will replace
       the whole tag.

       Indeed you cannot use "tal:content" and "tal:replace" in the same tag.

   omit-tag
       Abstract

         <tag tal:omit-tag="EXPRESSION">Some contents</tag>

       Example

         <b tal:omit-tag="not:bold">I may not be bold.</b>

       If "not:bold" is evaluated as TRUE, then the <b> tag will be omited.  If "not:bold" is
       evaluated as FALSE, then the <b> tag will stay in place.

       Why?

       omit-tag statements can be used to leave the contents of a tag in place while omitting the
       surrounding start and end tags if the expression which is evaluated is TRUE.

       TIP:

       If you want to ALWAYS remove a tag, you can use "omit-tag="string:1""

   on-error
       Warning: this is currently only partially implemented.  "on-error" may be used in Petal
       templates, but the expression isn't evaluated - Petal simply prints the expression as a
       string.

       Abstract

         <tag on-error="EXPRESSION">...</tag>

       Example

         <p on-error="string:Cannot access object/method!!">
           $object/method
         </p>

       Why?

       When Petal encounters an error, it usually dies with some obscure error message. The
       "on-error" statement lets you trap the error and replace it with a proper error message.

   using multiple statements
       You can do things like:

         <p tal:define="children document/children"
            tal:condition="children"
            tal:repeat="child children"
            tal:attributes="lang child/lang; xml:lang child/lang"
            tal:content="child/data"
            tal:on-error="string:Ouch!">Some Dummy Content</p>

       Given the fact that XML attributes are not ordered, withing the same tag statements will
       be executed in the following order:

           define
           condition
           repeat
               attributes
               content
           OR
               replace
           OR
               omit-tag
               content

       TRAP:

       Don't forget that the default prefix is "petal:" NOT "tal:", until you set the petal
       namespace in your HTML or XML document as follows:

           <html xmlns:tal="http://purl.org/petal/1.0/">

METAL MACROS

       Petal supports an implementation of the METAL specification, which is a very WYSIWYG
       compatible way of doing template includes.

   define-macro
       In order to define a macro inside a file (i.e. a fragment to be included), you use the
       metal:define-macro directive. For example:

         File foo.xml
         ============

         <html xmlns:metal="http://xml.zope.org/namespaces/metal">
           <body>
             <p metal:define-macro="footer">
               (c) Me (r)(tm) (pouet pouet)
             </p>
           </body>
         </html>

   use-macro
       In order to use a previously defined macro, you use the metal:use-macro directive.  For
       example:

         File bar.xml
         ============

         <html xmlns:metal="http://xml.zope.org/namespaces/metal">
           <body>
             ... plenty of content ...

             <p metal:use-macro="foo.xml#footer">
               Page Footer.
             </p>
           </body>
         </html>

   define-slot
       In any given macro you can define slots, which are bits of macros that can be overridden
       by something else using the fill-macro directive. To re-use the example above, imagine
       that we want to be able to optionally override the (pouet pouet) bit with something else:

         File foo.xml
         ============

         <html xmlns:metal="http://xml.zope.org/namespaces/metal">
           <body>
             <p metal:define-macro="footer">
               (c) Me (r)(tm) <span metal:define-slot="pouet">(pouet pouet)</span>
             </p>
           </body>
         </html>

   fill-slot
       Your including file can override any slot using the fill-slot instruction, i.e.

         File bar.xml
         ============

         <html xmlns:metal="http://xml.zope.org/namespaces/metal">
           <body>
             ... plenty of content ...

             <p metal:use-macro="foo.xml#footer">
               Page Footer. <span metal:fill-slot="pouet" petal:omit-tag="">(bar baz)</span>
             </p>
           </body>
         </html>

       This would result in the macro 'foo.xml#footer' to produce:

         <html>
           <body>
             <p>
               (c) Me (r)(tm) (bar baz)
             </p>
           </body>
         </html>

   self includes
       In Zope, METAL macros are expanded first, and then the TAL instructions are processed.
       However with Petal, METAL macros are expanded at run-time just like regular includes,
       which allows for recursive macros.

       This example templates a sitemap, which on a hierarchically organized site would be
       recursive by nature:

         <html xmlns:metal="http://xml.zope.org/namespaces/metal"
               xmlns:petal="http://purl.org/petal/1.0/">
           <body>
             <p>Sitemap:</p>

             <li metal:define-macro="recurse">
               <a href="#"
                  petal:attributes="href child/Full_Path"
                  petal:content="child/Title"
               >Child Document Title</a>
               <ul
                 petal:define="children child/Children"
                 petal:condition="children"
                 petal:repeat="child children"
               >
                 <li metal:use-macro="#recurse">Dummy Child 1</li>
                 <li petal:replace="nothing">Dummy Child 2</li>
                 <li petal:replace="nothing">Dummy Child 3</li>
               </ul>
             </li>
           </body>
         </html>

EXPRESSIONS AND MODIFIERS

       Petal has the ability to bind template variables to the following Perl datatypes: scalars,
       lists, hash, arrays and objects. The article describes the syntax which is used to access
       these from Petal templates.

       In the following examples, we'll assume that the template is used as follows:

         my $hashref = some_complex_data_structure();
         my $template = new Petal ('foo.xml');
         print $template->process ( $hashref );

       Then we will show how the Petal Expression Syntax maps to the Perl way of accessing these
       values.

   accessing scalar values
       Perl expression

         $hashref->{'some_value'};

       Petal expression

         some_value

       Example

         <!--? Replaces Hello, World with the contents of
               $hashref->{'some_value'}
         -->
         <span tal:replace="some_value">Hello, World</span>

   accessing hashes & arrays
       Perl expression

         $hashref->{'some_hash'}->{'a_key'};

       Petal expression

         some_hash/a_key

       Example

         <!--? Replaces Hello, World with the contents
               of $hashref->{'some_hash'}->{'a_key'}
         -->
         <span tal:replace="some_hash/a_key">Hello, World</span>

       Perl expression

         $hashref->{'some_array'}->[12]

       Petal expression

         some_array/12

       Example

         <!--? Replaces Hello, World with the contents
              of $hashref->{'some_array'}->[12]
         -->
         <span tal:replace="some_array/12">Hello, World</span>

       Note: You're more likely to want to loop through arrays:

         <!--? Loops trough the array and displays each values -->
         <ul tal:condition="some_array">
           <li tal:repeat="value some_array"
               tal:content="value">Hello, World</li>
         </ul>

   accessing object methods
       Perl expressions

         1. $hashref->{'some_object'}->some_method();
         2. $hashref->{'some_object'}->some_method ('foo', 'bar');
         3. $hashref->{'some_object'}->some_method ($hashref->{'some_variable'})

       Petal expressions

         1. some_object/some_method
         2a. some_object/some_method 'foo' 'bar'
         2b. some_object/some_method "foo" "bar"
         2c. some_object/some_method --foo --bar
         3. some_object/some_method some_variable

       Note that the syntax as described in 2c works only if you use strings which do not contain
       spaces.

       Example

         <p>
           <span tal:replace="value1">2</span> times
           <span tal:replace="value2">2</span> equals
           <span tal:replace="math_object/multiply value1 value2">4</span>
         </p>

   composing
       Petal lets you traverse any data structure, i.e.

       Perl expression

         $hashref->{'some_object'}
                 ->some_method()
                 ->{'key2'}
                 ->some_other_method ( 'foo', $hash->{bar} );

       Petal expression

         some_object/some_method/key2/some_other_method --foo bar

   true:EXPRESSION
         If EXPRESSION returns an array reference
           If this array reference has at least one element
             Returns TRUE
           Else
             Returns FALSE

         Else
           If EXPRESSION returns a TRUE value (according to Perl 'trueness')
             Returns TRUE
           Else
             Returns FALSE

       the "true:" modifiers should always be used when doing Petal conditions.

   false:EXPRESSION
       I'm pretty sure you can work this one out by yourself :-)

   set:variable_name EXPRESSION
       Sets the value returned by the evaluation of EXPRESSION in "$hash->{variable_name}". For
       instance:

       Perl expression:

         $hash->{variable_name} = $hash->{object}->method();

       Petal expression:

         set:variable_name object/method

   string:STRING_EXPRESSION
       The "string:" modifier lets you interpolate petal expressions within a string and returns
       the value.

         string:Welcome $user/real_name, it is $date!

       Alternatively, you could write:

         string:Welcome ${user/real_name}, it is ${date}!

       The advantage of using curly brackets is that it lets you interpolate expressions which
       invoke methods with parameters, i.e.

         string:The current CGI 'action' param is: ${cgi/param --action}

ADVANCED PETAL

   writing your own modifiers
       Petal lets you write your own modifiers, either using coderefs or modules.

       Coderefs

       Let's say that you want to write an uppercase: modifier, which would uppercase the result
       of an expression evaluation, as in:

         uppercase:string:Hello, World

       Would return

         HELLO, WORLD

       Here is what you can do:

         # don't forget the trailing colon in C<uppercase:> !!
         $Petal::Hash::MODIFIERS->{'uppercase:'} = sub {
             my $hash = shift;
             my $args = shift;

             my $result = $hash->fetch ($args);
             return uc ($result);
         };

       Modules.

       You might want to use a module rather than a coderef. Here is the example above
       reimplemented as a module:

           package Petal::Hash::UpperCase;
           use strict;
           use warnings;

           sub process {
             my $class = shift;
             my $hash  = shift;
             my $args  = shift;

             my $result = $hash->fetch ($args);
             return uc ($result);
           }

           1;

       As long as your module is in the namespace Petal::Hash::<YourModifierName>, Petal will
       automatically pick it up and assign it to its lowercased name, i.e. in our example
       "uppercase:".

       If your modifier is OUTSIDE Petal::Hash::<YourModifierName>, you need to make Petal aware
       of its existence as follows:

         use MyPetalModifier::UpperCase;
         $Petal::Hash::MODIFIERS->{'uppercase:'} = 'MyPetalModifier::UpperCase';

Expression keywords

       XML encoding / structure keyword

       By default Petal will encode "&", "<", ""> and """ to "&amp;", "&lt;", &gt and "&quot;"
       respectively. However sometimes you might want to display an expression which is already
       encoded, in which case you can use the "structure" keyword.

         structure my/encoded/variable

       Note that this is a language keyword, not a modifier. It does not use a trailing colon.

       Petal::Hash caching and fresh keyword

       Petal caches the expressions which it resolves, i.e. if you write the expression:

         string:$foo/bar, ${baz/buz/blah}

       Petal::Hash will compute it once, and then for subsequent accesses to that expression
       always return the same value. This is almost never a problem, even for loops because a new
       Petal::Hash object is used for each iteration in order to support proper scoping.

       However, in some rare cases you might not want to have that behavior, in which case you
       need to prefix your expression with the "fresh" keyword, i.e.

         fresh string:$foo/bar, ${baz/buz/blah}

       You can use "fresh" with "structure" if you need to:

         fresh structure string:$foo/bar, ${baz/buz/blah}

       However the reverse does not work:

         <!--? VERY BAD, WON'T WORK !!! -->
         structure fresh string:$foo/bar, ${baz/buz/blah}

   TOY FUNCTIONS (For debugging or if you're curious)
       perl -MPetal -e canonical template.xml

       Displays the canonical template for template.xml.  You can set $Petal::INPUT using by
       setting the PETAL_INPUT environment variable.  You can set $Petal::OUTPUT using by setting
       the PETAL_OUTPUT environment variable.

       perl -MPetal -e code template.xml

       Displays the perl code for template.xml.  You can set $Petal::INPUT using by setting the
       PETAL_INPUT environment variable.  You can set $Petal::OUTPUT using by setting the
       PETAL_OUTPUT environment variable.

       perl -MPetal -e lcode template.xml

       Displays the perl code for template.xml, with line numbers.  You can set $Petal::INPUT
       using by setting the PETAL_INPUT environment variable.  You can set $Petal::OUTPUT using
       by setting the PETAL_OUTPUT environment variable.

   What does Petal do internally?
       The cycle of a Petal template is the following:

           1. Read the source XML template
           2. $INPUT (XML or HTML) throws XML events from the source file
           3. $OUTPUT (XML or HTML) uses these XML events to canonicalize the template
           4. Petal::CodeGenerator turns the canonical template into Perl code
           5. Petal::Cache::Disk caches the Perl code on disk
           6. Petal turns the perl code into a subroutine
           7. Petal::Cache::Memory caches the subroutine in memory
           8. Petal executes the subroutine
           9. (optional) Petal internationalizes the resulting output.

       If you are under a persistent environment a la mod_perl, subsequent calls to the same
       template will be reduced to step 8 until the source template changes.

       Otherwise, subsequent calls will resume at step 6, until the source template changes.

       If you are using the mod_perl prefork MPM, you can precompile Petal templates into
       Apache's shared memory at startup by using the cache_only option.  This will allow you to
       run through steps 1-7 without passing any data to Petal.

DECRYPTING WARNINGS AND ERRORS

   "Cannot import module $module. Reason: $@" (nonfatal)
       Petal was not able to import one of the modules. This error warning will be issued when
       Petal is unable to load a plugin because it has been badly install or is just broken.

   "Petal modifier encode: is deprecated" (nonfatal)
       You don't need to use encode:EXPRESSION to XML-encode expression anymore, Petal does it
       for you. encode: has been turned into a no-op.

   Cannot find value for ... (FATAL)
       You tried to invoke an/expression/like/this/one but Petal could not resolve it. This could
       be because an/expression/like evaluated to undef and hence the remaining this/one could
       not be resolved.

       Usually Petal gives you a line number and a dump of your template as Perl code. You can
       look at the perl code to try to determine the faulty bit in your template.

   not well-formed (invalid token) at ... (FATAL)
       Petal was trying to parse a file that is not well-formed XML or that has strange entities
       in it. Try to run xmllint on your file to see if it's well formed or try to use the
       $Petal::INPUT = 'XHTML' option.

   other errors
       Either I've forgot to document it, or it's a bug. Send an email to the Petal mailing list.

EXPORTS

       None.

AUTHOR

       Copyright 2003 - MKDoc Ltd.

       Authors: Jean-Michel Hiver,
                Fergal Daly <fergal@esatclear.ie>,       and others.

       This module free software and is distributed under the same license as Perl itself. Use it
       at your own risk.

       Thanks to everybody on the list who contributed to Petal in the form of patches, bug
       reports and suggestions. See README for a list of contributors.

SEE ALSO

       Join the Petal mailing list:

         http://lists.webarch.co.uk/mailman/listinfo/petal

       Mailing list archives:

         http://lists.webarch.co.uk/pipermail/petal

       Have a peek at the TAL / TALES / METAL specs:

         http://wiki.zope.org/ZPT/TAL
         http://wiki.zope.org/ZPT/TALES
         http://wiki.zope.org/ZPT/METAL