[MKDoc-commit] Section on producing valid XML from William McKee

Fri Jan 21 17:52:41 GMT 2005

Log Message:
-----------
Section on producing valid XML from William McKee

Modified Files:
--------------
    Petal/lib/Petal:
        Cookbook.pod

-------------- next part --------------
Index: Cookbook.pod
===================================================================
RCS file: /var/spool/cvs/Petal/lib/Petal/Cookbook.pod,v
retrieving revision 1.2
retrieving revision 1.3
diff -Llib/Petal/Cookbook.pod -Llib/Petal/Cookbook.pod -u -r1.2 -r1.3

--- lib/Petal/Cookbook.pod
+++ lib/Petal/Cookbook.pod
@@ -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
