[Jifty-commit] r4022 - Template-Declare/lib/Template

[jifty-commit at lists.jifty.org]

Author: agentz
Date: Sat Sep  1 00:30:04 2007
New Revision: 4022

Modified:
   Template-Declare/lib/Template/Declare.pm

Log:
TD - moved the PITFALLS section to the right place

Modified: Template-Declare/lib/Template/Declare.pm
==============================================================================
--- Template-Declare/lib/Template/Declare.pm	(original)
+++ Template-Declare/lib/Template/Declare.pm	Sat Sep  1 00:30:04 2007
@@ -267,76 +267,6 @@
 
 =back
 
-=head2 PITFALLS
-
-We're reusing the perl interpreter for our templating langauge, but Perl was not designed specifically for our purpose here. Here are some known pitfalls while you're scripting your templates with this module.
-
-=over
-
-=item *
-
-It's quite common to see tag sub calling statements without trailing semi-colons right after C<}>. For instance,
-
-    template foo => {
-        p {
-            a { attr { src => '1.png' } }
-            a { attr { src => '2.png' } }
-            a { attr { src => '3.png' } }
-        }
-    };
-
-is equivalent to
-
-    template foo => {
-        p {
-            a { attr { src => '1.png' } };
-            a { attr { src => '2.png' } };
-            a { attr { src => '3.png' } };
-        };
-    };
-
-But C<xml_decl> is a notable exception. Please always put a trailing semicolon after C<xml_decl { ... }>, or you'll mess up the outputs.
-
-=item *
-
-Another place that requires trailing semicolon is the statements before a Perl looping statement, an if statement, or a C<show> call. For example:
-
-    p { "My links:" };
-    for (@links) {
-        with( src => $_ ), a {}
-    }
-
-The C<;> after C< p { ... } > is required here, or Perl will complaint about syntax errors.
-
-=item *
-
-Literal strings that have tag siblings won't be captured. So the following template
-
-    p { 'hello'; em { 'world' } }
-
-produces
-
-  <p>
-   <em>world</em>
-  </p>
-
-instead of the desired output
-
-  <p>
-   hello
-   <em>world</em>
-  </p>
-
-You can use C<outs> here to solve this problem:
-
-    p { outs 'hello'; em { 'world' } }
-
-Note you can always get rid of the C<outs> crap if the string literal is the only element of the containing block:
-
-   p { 'hello, world!' }
-
-=back
-
 =cut
 
 sub init {
@@ -656,9 +586,79 @@
     return $TEMPLATE_VARS->{$self};
 }
 
+=head1 PITFALLS
+
+We're reusing the perl interpreter for our templating langauge, but Perl was not designed specifically for our purpose here. Here are some known pitfalls while you're scripting your templates with this module.
+
+=over
+
+=item *
+
+It's quite common to see tag sub calling statements without trailing semi-colons right after C<}>. For instance,
+
+    template foo => {
+        p {
+            a { attr { src => '1.png' } }
+            a { attr { src => '2.png' } }
+            a { attr { src => '3.png' } }
+        }
+    };
+
+is equivalent to
+
+    template foo => {
+        p {
+            a { attr { src => '1.png' } };
+            a { attr { src => '2.png' } };
+            a { attr { src => '3.png' } };
+        };
+    };
+
+But C<xml_decl> is a notable exception. Please always put a trailing semicolon after C<xml_decl { ... }>, or you'll mess up the outputs.
+
+=item *
+
+Another place that requires trailing semicolon is the statements before a Perl looping statement, an if statement, or a C<show> call. For example:
+
+    p { "My links:" };
+    for (@links) {
+        with( src => $_ ), a {}
+    }
+
+The C<;> after C< p { ... } > is required here, or Perl will complaint about syntax errors.
+
+=item *
+
+Literal strings that have tag siblings won't be captured. So the following template
+
+    p { 'hello'; em { 'world' } }
+
+produces
+
+  <p>
+   <em>world</em>
+  </p>
+
+instead of the desired output
+
+  <p>
+   hello
+   <em>world</em>
+  </p>
+
+You can use C<outs> here to solve this problem:
+
+    p { outs 'hello'; em { 'world' } }
+
+Note you can always get rid of the C<outs> crap if the string literal is the only element of the containing block:
+
+   p { 'hello, world!' }
+
+=back
+
 =head1 BUGS
 
-Crawling all over, baby. Be very, very careful. This code is so cutting edge, it can only be fashioned from carbon nanotubes.
+Crawling all over, baby. Be very, very careful. This code is so cutting edge, it can only be fashioned from carbon nanotubes. But we're already using this thing in production :) Make sure you have read the PITFALL section above :)
 
 Some specific bugs and design flaws that we'd love to see fixed.