---------------------
PTM LANGUAGE OVERVIEW
---------------------

  Definition of terms:
    PTM   - The name of the language, short for "Perl Template"
    PPA   - Short for "PTM Parser Application", refers to the "ptm.cgi" file
    PTMDB - PTM's Database interface module

  PTM, allows for inline Perl/HTML.  More precicely, it allows you to put Perl
  code right in the middle of your HTML. To facilitate users that are used to
  working in the popular PHP language, the following global variables have been
  created:

    %_SERVER    - PTM equivalent of PHP's _SERVER variable
    %_GET       - PTM equivalent of PHP's _GET variable
    %_POST      - PTM equivalent of PHP's _POST variable

  Additionally some other globals are hanging around for your use:

    $_VERSION     - Current PPA version installed (PTM Language Version)
    $_URL         - Full requested URL, not including any "?name=value"
                    additions
    $_PATH        - The physical system path to your PTM script, not including
                    the PTM script's file name -- slash terminated (/)
    $_BASE        - The URL path to your PTM script, not including the PTM
                    script's file name -- slash terminated (/)
    $_SCRIPT      - The file name of the PTM script being called
    $_CGI         - A Perl CGI object. Direct Access to CGI module capability
    @_KEYWORDS    - Stores GET method postings without matching "=value" when
                    there is GET data, but no name=value pairs have been entered
    $_HEADER      - The HTTP header to be printed before the page to let the
                    browser know what kind of information is coming and what to
                    do with it
    %_SET_COOKIES - A hash containing the "Set-Cookie:" strings that are to be
                    written as part of the HTTP header -- rarely accessed
                    directly
    %_COOKIES     - The cookies stored in the users' browser. This includes
                    all cookies, both session and time-based, except those
                    with "PTMSESSION___" names, which are used to facilitate
                    PTM sessions, and are stored in %_SESSION
    %_SESSION     - Similar to the %_COOKIES variable, this has stores all PTM
                    session cookies. The cookie names are atripped of their
                    leading "PTMSESSION" characters before being entered
                    into the hash -- therefore, "PTMSESSIONID" becomes "ID"

  And there are a few more that you probably shouldn't touch =)
  
    $_SYNTAX_...      - These variables define how the PTM language itself is
                        formed and should ONLY be changed by very experienced
                        PTM developers
    @_PTM             - Stores the formatted Perl snippets to be evaluated and
                        printed, and should NEVER be modified during run-time
                        -- unless of course you are trying to crash your own
                        site, then by all means go ahead =)
    $_PTM_POS         - Tells the snippets going into @_PTM where and in what
                        order they are to be printed. Just as above, this should
                        never be modified at run-time.
    $_PTM_PREPROCESS  - Stores the code from PREPROCESS tags and, though it
                        COULD be modified during run time, it would most likely
                        have no effect
    @_REQUIRE         - Stores PTM Perl module names from the REQUIRE tag to
                        be loaded immediately before preprocessing.

  There are, of course, also $_DOCUMENT_ROOT and $_DEFAULT_PTM_FILE which
  are the first variables defined and are used to tell the PPA where to look
  for data.

  If you are familiar with PHP the first three globals above should look
  familiar. The only real difference in their usage is that Perl syntax must be
  used instead of PHP. The most noticable difference is the use of curly braces
  {} instead of square brackets [] when retrieving a value --
  e.g. $_POST{'name'}

  As with any language, PTM is best explained through example, so here are some
  samples of how to use each of the above mentioned PHP-like globals -- each
  example assumes you are somewhere in the middle of an PTM/HTML document and
  wish to insert the given value at that point:

  Displaying the server software information (italic):

    <i><?= $_SERVER{'SERVER_SOFTWARE'} ?></i>

  Displaying the value of a "name" form input using the GET method (bold):

    <b><?= $_GET{'name'} ?></b>

  Listing the names and values of all POSTed form inputs (table):

    <table>
      <? foreach $input (keys %_POST) { ?>
      <tr>
        <td><?= $input ?>: </td>
        <td><?= $_POST{$input} ?></td>
      </tr>
      <? } ?>
    </table>

  As you can see above different tag types are used, always beginning and ending
  with '<?' and '?>'.  But additionally you will note the use of '<?='. This
  denotes a DISPLAY tag.  There are five (5) tag types in PTM as of version 0.3:

    DO          - <?
    DISPLAY     - <?=
    TEMPLATE    - <?|
    FILE        - <?!
    NOHTML      - <?*
    REQUIRE     - <?~
    PREPROCESS  - <?:

  For those that prefer, the word may be substituted in place of the denoting
  symbol -- e.g. '<?display' is the same as '<?='. Also, it is important that
  white space (space, tab, carriage return, or line feed) be placed after the
  opening tag and before the closing tag. Meaning that "<?= $_VERSION ?>" works
  but "<?=$_VERSION?>" does not. This is to avoid the mixing and confusion of
  tag values and intended Perl code within the PPA. Another note, though all PTM
  tags can be closed with the standard '?>' they may also be closed using the
  same symbols with which they were opened, which might be used if you have a
  lot of content within a PTM tag and need to know specifically which type of
  tag closing you are looking at -- meaning "<?= $_VERSION =?>" is the same as
  "<?= $_VERSION ?>". And of course you can mix and match using the symbols and
  words, like "<?display $_VERSION =?>".

  DO tags

    Whatever is inside of them is run as straight perl code. Use semicolons (;)
    where appropriate to "end your Perly thought" ;)

  DISPLAY tags

    Behind the scenes this runs Perl's "print" statement on the contents, so
    make sure content is formatted accordingly -- meaning use quotes and dots to
    denote text and concatenation.

  TEMPLATE tags

    Used to import another text file in place of the tag in PTM format --
    meaning the contents will be evaluated as a PTM file. Because variables can
    be used to denote file name or parts of file names, tag contents will be
    read as they would be in Perl -- meaning use quotes and dots to denote text
    and concatenation.

  FILE tags

    Used to import another file in place of the tag in plain text/HTML format
    -- meaning no PTM tags will be evaluated in the imported text

  NOHTML tags

    Same as FILE tags (no PTM tags are evaluated) except that the standard HTML
    characters "&<> will be converted to their ordinal macro equivalents. For
    example, the ampersand symbol (&) is replaced with "&#38;". This means that
    these characters will show up in your HTML document as text, and will not
    be formatted as HTML. Use this format to openly display yout PTM/HTML
    documents, or to disable HTML characters when showing a text file that may
    contain these characters.
    
    IMPORTANT NOTE:
      DO NOT use NOHTML tags to display any PTM/HTML documents that may contain
      sensitive information such as user names, passwords, database login info,
      etc., as ALL PTM and HTML are shown in their entirety.

  PREPROCESS tags

    Used when you want to process something BEFORE the normal PTM statements are
    run. Most commonly used for setting up cookies, sessions, and the HTTP
    header, the contents of the PREPROCESS tag are NOT a part of the rest of
    your PTM script. Any variables defined here will NOT be carried over into
    your DO, DISPLAY, etc. tags. Only modification of predefined global
    variables will be carried over from PREPROCESS tags to your normal script.
    Regardless of where you place PREPROCESS tags in your script, they will
    ALWAYS be run first.
    
    Because PREPROCESS tags are evaluated BEFORE the HTTP header is printed,
    print statements should not be used here. Other than that, they work
    basically the same as DO tags.

  REQUIRE tags

    These tags are used to include Perl modules into your PTM script. Like the
    PREPROCESS tag, the REQUIRE tags are evaluated BEFORE any of your normal PTM
    script. As a matter of fact, they are the very first thing to be evaluated,
    regardless of where they are placed in your PTM script. They are important
    because they are the only means of including a module into BOTH your
    PREPROCESS and regular PTM tags at the same time and are, therefore, the
    preferred method of requiring external non-PTM/HTML files. "require"
    statements are used to include Perl modules into your Perl code at run-time,
    whereas "use" statements are used to include them at compile time. As
    all PTM is processed at run-time, the "use" statement is not necessary.

  Quick Tag Examples:

  DO tags

    <? $a = $b + $c; ?>
    <? for($x=1;$x<5;$x++){ ?>html<? } ?>
    
  DISPLAY tags

    <?= $_VERSION ?>
    <?= "Version: " . $_VERSION ?>
    
  TEMPLATE tags

    <?| "file1.ptm" ?>
    <?| 'file' . $f . '.ptm' ?>
    <?| "file$f.ptm" ?>
    
  FILE tags

    <?! "file1.txt" ?>
    <?! 'file' . $f . '.txt' ?>
    <?! "file$f.txt" ?>

  NOHTML tags

    <?* "file1.txt" ?>
    <?* 'file' . $f . '.txt' ?>
    <?* "file$f.txt" ?>

  PREPROCESS tags

    <?: if ($_COOKIE{'url'}) { &set_redirect_header($_COOKIE{'url'}, 5); } ?>
    <?: if ($_POST{'user'}) { &start_session($_POST{'user'}); } ?>

  REQUIRE tags

    <?~ PTMDB ?>
    <?~ PTMDB.pm ?>
    <?~ PTMDB MyModule.pm Other.pl ?>

  Those are the basics to get you started. See the PTM online documentation for
  more information.

  That's all for now! ;)