What is PTML/Ptml?

PTML is a simple but non-trivial language used to build templates into which
data can be merged.

Ptml.pm is the Perl module that understands PTML.

The Ptml package includes Ptml.pm and some examples and additional
documentation.

To use PTML you write a template file containing PTML statements and a Perl
script that defines the data you wish to merge into the template.  The
script calls one of the Ptml functions to perform the merge, and the result
is output to a file handle (typically but not necessarily STDOUT).


Features of PTML

PTML is _not_ an extension to HTML.  In my experience it is difficult to
prepare HTML templates using a template language that is an extension to
HTML because a standard browser "hides" the template logic.  In contrast, an
unmerged PTML file viewed with a standard browser typically gives a good
representation of what the final merged HTML document will look like.

Ptml is small and self contained, and requires no setups or installations
within Perl or the computers operating environment.  Simply copy the Ptml.pm
file to a suitable directory and it's ready to go.  

Complex templates can be debugged with the set_verify() function, which
prints every line of a template as it is merged along with macro expansion
phases.

Ptml can gather all visual elements into a single file which is separate
from the code BUT the visual elements are not _isolated_ from the code. Ptml
trusts the creator of the Ptml file, and they automatically have full access
to both Perl and the Perl variables of the application.

The above paragraph talks about "a single file" but the setup of Ptml is
more flexible than this.  More than one template file can be used if desired
(which is useful in a larger project), or the visual template can be
incorporated right into the Perl source code itself (useful for very small
projects).


Installing Ptml.

Copy Ptml.pm into a suitable directory.

For system wide installation I suggest the Text/Template directory (which
you must probably create).

In this case Ptml will be accessed like this

   use Text::Template::Ptml;

Ptml can be installed on a project by project basis instead if you wish.  If
Ptml.pm is stored in the same directory as the rest of your Perl application
then you would access it with code like

   use Ptml;

If it were installed in a subdirectory such as Utils it would be accessed
with code like

   use Utils::Ptml;


Examples of merging

   See `example.ptml' for examples of all the PTML features, especially the
   more complex ones.

   The doPtml utility can be used to examine the examples template, or other
   files if desired.