[Petal] Reviving the Petal Cookbook

Fri Jan 21 17:46:57 GMT 2005

On Fri, Jan 21, 2005 at 12:34:15PM +0000, Bruno Postle wrote:
> Ok, added to CVS, though I removed the dependency on Petal::Utils.

Thanks. One more change which adds a new topic about creating valid
documents (I've been dealing with this issue all week as you may have
noticed :).


Thanks,
William

-- 
Knowmad Services Inc.
http://www.knowmad.com
-------------- next part --------------
Index: Cookbook.pod
===================================================================
RCS file: /var/spool/cvs/Petal/lib/Petal/Cookbook.pod,v
retrieving revision 1.2
diff -u -r1.2 Cookbook.pod

--- Cookbook.pod	21 Jan 2005 12:31:44 -0000	1.2
+++ Cookbook.pod	21 Jan 2005 17:45:19 -0000
@@ -20,7 +20,7 @@
 When using Petal for web application development, your templates should not
 need to be accessible by the webserver. In fact, it could be a security
 risk if they are available since there may be code or comments which users
-should not see prior to processing by Petal. Thus, you should strive to store
+should not see prior to processing by Petal. Thus, it is recommended to store
 your templates in a non-web accessible directory. Personally I prefer to place
 the directory outside of the web root but you could also use permissions or
 .htaccess files to control access to the directory. This directory path should
@@ -30,8 +30,55 @@
 
 =head2 Template naming
 
-Although not necessary, I like to name my templates with the .tmpl extension
-to help myself and designers distinguish templates from static html.
+Petal is indifferent about the name of the template files. Personally, I like
+to name my templates with the .tmpl extension to help myself and designers
+distinguish templates from static html. Some GUI editors, though, will not
+open files without a htm/html extension (esp. under Windows).
+
+
+=head2 Fixing invalid templates (Is this XML well-formed?)
+
+If you are getting a parse_error when trying to process your template, you
+will need to clean up your XHTML template in order for Petal to process it.
+Two tools will be of great assistance in taking the step towards better
+standards compliance--HTML Tidy (L<http://tidy.sf.net>) and xmllint. In
+addition, you can use the page validation services at W3C
+(L<http://validator.w3.org/>). Alternatively, you could use the
+L<Petal::Parser::HTB> module which will parse non well-formed HTML documents
+using L<HTML::TreeBuilder>.
+
+HTML Tidy will rewrite your document into valid XHTML and, if requested, even
+replace legacy formatting tags with their CSS counterparts. You can safely
+ignore the warnings about proprietary attributes. Be sure to read the output
+of what HTML Tidy is doing or else you may find it removing important tags
+which it thinks are empty or invalid (e.g., inline elements outside of a
+block). One of the important options that should be set is output_xhtml
+(-asxhtml from the command-line).  Here's an example of how to use it (see the
+documentation for complete details):
+
+  tidy --asxhtml original_file.html > new_file.html
+
+Once your document is well-formed, you can use xmllint to do day-to-day
+checking that it stays well-formed without having to wade through the warnings
+that HTML Tidy will generate about proprietary attributes. The following command will check that a document is well-formed:
+
+  xmllint --noout <filename>
+
+To prevent errors about undefined namespace prefix, be sure to include these
+in your template like so:
+
+  <html xmlns="http://www.w3.org/1999/xhtml"
+   xmlns:petal="http://purl.org/petal/1.0/"
+   xmlns:metal="http://purl.org/petal/1.0/">
+
+You may receive errors from xmllint about unknown entities such as nbsp. These
+can be safely ignored. If you find a way to suppress these warnings, please
+let us know. In the meantime, you can pass the output through grep to ignore
+these bogus warnings:.
+
+  xmllint --noout  tmpl/contact_info.tmpl >& grep -v 'Entity'
+
+Now you have no excuse for not creating well-formed XHTML documents.
 
 
 =head2 Passing a hashreference to Petal::process
