#========================================================================
#
# Text::MetaText 
#
#   Version 0.19
# 
#   Copyright (C) 1996-1998 Andy Wardley <abw@kfs.org>.  
#   All Rights Reserved.
#
#------------------------------------------------------------------------
#
# Features
#
#   This file gives a general overview of the features of Text::MetaText.
#   Considering, in particular, the number of various text/template 
#   processing modules available in CPAN, this file should help the 
#   potential user determine if the module is suitable for their needs.
#
#   A brief description of some of the other text/template processing 
#   modules available follows the Text::MetaText features list.
#
#========================================================================

MetaText is a (yet another) text processing and markup meta-language 
which can be used for processing "template" files. 

Like a glorified pre-processor, MetaText can; include files, define 
and substitute variable values, execute conditional actions based on 
variables, call other perl functions or object methods and capture the 
resulting output back into the document, and more. It can format the 
output of any of these operations in a number of ways. The 
objects, and inherently, the format and semantics of the MetaText 
langauge itself, are highly configurable.

MetaText does *not* evaluate any code using perl's 'eval' function.
This makes it safe to use in an environment where the input cannot
be verified or trusted.  The implications of a malicious (or possibly 
accidental) directive in a document are serious:

    Some document, blah, blah, blah
    %% system('rm -fr *') %%       # not a problem with MetaText
    more generic document stuff, blah, blah
  
On the other hand, a text processing system that allows embedded perl 
programs to be executed is naturally far more powerful.  MetaText is not 
that beast.  There are several other modules which perform that task 
admirably, as described in the final section below.

What MetaText benefits from this approach is that the syntax is greatly
simplified.  Web Designers, for example, who have no knowledge of perl
or desire to learn (shame on them!) can quite happily use MetaText to 
markup template documents and rely on its limited but powerful range of 
features to get the job done quickly and well.  MetaText supports a 
number of directives that have functionality "built in" such as 
INCLUDE which processes and inserts the contents of an external file.

When the default MetaText command set simply isn't enough, an EXECUTE 
configuration flag can be set to allow externally defined functions or 
class methods to become part of the syntax.  In this way, it is possible
to extend MetaText quickly and easily to execute any arbitrary perl in a 
safe and restricted manner.


#------------------------------------------------------------------------
# About MetaText
#------------------------------------------------------------------------

* MetaText is written entirely in Perl 5.

* MetaText is free software.  You are free to use, distribute and modify
  it under the terms of the Perl Artistic License.

* MetaText is fully object-oriented and does not pollute the caller's
  namespace.

* MetaText is well documented and the code is thoroughly commented.
  An ever-growing test suite is included to test the processor and 
  provide user examples.

* MetaText is beta-test software but is reliable and roadworthy.  
  It has been developed and tested over a number of years and is now 
  generally very stable.  
  
* The interface _may_ change in future versions.  It is for this reason 
  that MetaText is still "in beta".  Every effort has, and will be made
  to maintain backwards compatibility.  No major interface changes are
  planned that will not be backwardly compatible.

* MetaText is '-w' and 'use strict' compliant.

* MetaText is Y2k compliant, however nonsensical that notion may be.


#------------------------------------------------------------------------
# Feature Summary
#------------------------------------------------------------------------

* Text files and strings can be processed and any embedded directives 
  are expanded.

* Directives may be placed anywhere in a text file or string and are
  enclosed in 'magic' tokens which may be user-defined tokens 
  (default: '%%'):

    some text, blah, blah, %% INCLUDE some/file %% yah, yah, yah
    with user-defined tokens:  <!-- INCLUDE some/file --> etc., etc

* Directives may contain any whitespace, including blank lines:

    %%
        INCLUDE foo/bar

        var1 = valA
        var3 = valB
        no_space=no_problem
    %%

* Significant whitespace should be quoted

    %% INCLUDE me
       name = "Andy Wardley"
    %%

* Directive names may be specified in either case (although UPPER CASE
  is recommended for clarity)

    %% INCLUDE foo %%
    %% include bar %%

* Variables can be defined in the calling perl code or within a 
  template document itself:

    %% DEFINE foo=bar baz="A string" %%

* Variables can be interpolated into the document:

    %% foo %%   (the verbose version is '%% SUBST foo %%')

* Variables can be interpolated into other variables:

    %% DEFINE rootpath=/home/abw       %%
    %% DEFINE imgpath=$rootpath/images %%

* Variable names can be treated case sensitively or insensitively 
  (default).

    %% DEFINE config="-vaf" %%
    %% config %%  %% CONFIG %%  %% Config %%   # all OK by default

* The INCLUDE directive can be used to import (and process) other files:

    %% INCLUDE header %%

* Directives (including INCLUDE) can be nested inside other files.

* Variables can be used to specify the INCLUDE filename:

    %% DEFINE header=abw/graphics/header %%
    %% INCLUDE $header %%

* A 'LIB' configuration variable specifies one or more directories where
  included (via INCLUDE) files are to be found.  Absolute file paths can 
  also be specified.

* Additional variable definitions can be added to an INCLUDE directive.
  All variable values are inherited by sub-documents (as per SGML/XML, 
  etc) and changes are locally scoped.

    %% INCLUDE my_html_header
       title   = "My Home Page"
       bgcolor = "#ffffff"
    %%

* BLOCK elements can be defined within a document to avoid having to 
  INCLUDE a separate file:

    <table>
    %% INCLUDE table_line id=tom name="Thomas Trumpton" %%
    %% INCLUDE table_line id=dic name="Richard Chigley" %%
    </table>

    %% BLOCK table_line %%
    <tr>
        <td>%% id %%</td>
        <td>%% name %%</td>
    </tr>
    %% ENDBLOCK %%

* All variable specification and interpolation options apply equally to 
  '%% INCLUDE <block> %%' directives as to '%% INCLUDE <file> %%'.

* The parsed contents of include files and defined blocks are cached
  internally to increase the speed of repetitive processing.  This gives 
  a significant performance boost, particularly when processing multiple 
  files or when using a persitant MetaText object (as you might with 
  mod_perl, for example).

* Complex conditional statements can be specified in INCLUDE directives
  to specify (at 'run-time') if the file or block should be included or
  ignored:

    %% INCLUDE myfile 
       if = "xyz < $max && (name =~ /Wardley/ || id in 'tom,dick,harry')" 
    %%

* 'unless' is similar, but negates the evaluation:

    %% INCLUDE higfx/header unless=textmode %%

* Standard and user-definable filters can be used to post-process the 
  contents of included files or blocks:

    %% INCLUDE myfile
       filter = escape(['])
    %%

    %% INCLUDE myblock
       filter = my_own_filter(param1, param2, etc)
    %%

* printf-like formats may also be specified for post-processing

    %% INCLUDE myfile
       format = "## %72s ##"
    %%

* An __END__ or __MTEND__ marker can be placed in the input text to mark
  the point at which processing should stop.  Certain MetaText directives
  (such as BLOCK...ENDBLOCK definitions) can be specified after this 
  point and incorporated into the document proper.

    %% INCLUDE myblock %%

    __MTEND__
    %% BLOCK myblock %% This is my block %% ENDBLOCK %%

* The EXECUTE configuration options allows class methods and perl 
  functions to be executed as directives.  Variables can be defined 
  in the normal way and get passed to the function as a hash reference:

    %% my_function 
       name = Fred
       age  = 42
    %%
  
* MetaText has user-definable error reporting and a comprehensive
  debug facility.

* MetaText is ideally suited to web content creation for both 
  static (processed off-line) and dynamically generated web pages, as 
  well as many other tasks.  


#------------------------------------------------------------------------
# The 'metapage' Processor.
#------------------------------------------------------------------------

The 'metapage' processor is a utility script that is distributed as part
of the Text::MetaText package (in the distribution 'bin' directory and 
installed to your perl bin directory when you 'make install').  

It may be convenient to think of metapage as the MetaText equivalent of 
make(1S), but nicer.  :-)

* Versatile configuration allows multiple profiles to be defined and 
  incorporated easily.

* MetaText configuration items and pre-defined variables can be specified
  in metapage config files.

* Numerous command-line options are available to tailor behaviour.

* Can traverse document trees examining time stamps to determine which 
  files should be processed.



#========================================================================
#
# Other Text/Template Processing Modules
#
#   This section lists some of the other text/template processing 
#   modules available from CPAN.  This list is not comprehensive either 
#   in the number of modules included, or in the detail in which they are 
#   described.  
#
#   As the author of Text::MetaText, I am naturally enamoured to my own 
#   solution and as such, my opinion is likely to be biased.  I have 
#   tried to briefly summarise the key features of each module as I 
#   understand them, but I would urge the reader to examine the 
#   relevant documentation in detail to get the full picture.
#
#   I welcome corrections and additions from the modules' authors or 
#   indeed anyone else who has a more comprehensive understanding of 
#   these packages than I.
#
#========================================================================

#------------------------------------------------------------------------
# Parse::ePerl by Ralf S. Engelschall <rse@engelschall.com>
#------------------------------------------------------------------------

ePerl interprets an ASCII file bristled with Perl 5 program
statements by evaluating the Perl 5 code while passing through
the plain ASCII data.  ePerl is an ANSI C program that actually
embedds a perl processor within itself.  Code within '<: ... :>'
blocks is evaluated and all other text is passed through.

Example:
    #!/path/to/eperl
    foo bar
    baz quux
    <: for ($i = 0; $i < 10; $i++) { print "foo #${i}\n"; } :>
    foo bar
    baz quux

See:
    http://www.engelschall.com/sw/eperl/


#------------------------------------------------------------------------
# Text::Vpp by Dominique Dumont <Dominique_Dumont@grenoble.hp.com>
#------------------------------------------------------------------------

A fast and lightweight pre-processor which is a suitable replacement
for cpp or m4.  Supports @INCLUDE, @EVAL, @IF, @ELSIF and @ENDIF 
statements.  Statements must be placed at the start of a line but may
be prefixed with any user-defined character.  Includes a 'vpp' 
script which encapsulates the module for processing files directly
from the command line.

Example:

    @INCLUDE inc_text.txt
    @EVAL $var2 = 1
    @IF $var2
    We should see this line
    @ELSE
    But not this one
    @ENDIF
     

#------------------------------------------------------------------------
# Text::Template by Mark-Jason Dominus <mjd@pobox.com>
#------------------------------------------------------------------------

A generic template processing module which allows tiny perl programs
to be embedded in text files.  When a template is filled in, the perl
programs are evaluated, and replaced with their values.  Simple and 
fast yet versatile.

Example:
 
    Dear {$title} {$lastname},
      
    It has come to our attention that you are delinquent 
    in your {$last_paid_month} payment.  Please remit 
    ${sprintf("%.2f", $amount)} immediately, or your patellae 
    may be needlessly endangered.
   
