
                                    P M P P

                           A Poor Man's Pre-Processor

                 Copyright (C) 1999  Kevin Pulo, kev@zip.com.au

Version 0.02
$Id: README,v 1.4 1999/02/22 12:04:06 kev Exp kev $


What is pmpp?
--------------
pmpp is a Poor Man's Pre-Processor, implemented in Python.  It can be used
to preprocess text such as complicated HTML, forms, and so on.  pmpp has
been designed to be used in situations where something like sed isn't quite
powerful enough, but a system like PHP3 or an SQL database is overkill or
not available.


pmpp history
-------------
I needed to churn out some fairly repetitive HTML (which would otherwise
have required lots of copy and pasting, followed by customisation of the
pasted bit), but my ISP hasn't yet installed PHP3 (and I'm too lazy to
learn style sheets).  sed couldn't handle the kind of thing I was after, so
I hacked up pmpp in Python.  The first revision was very specific to the
immediate problem that I had.  However, I soon released that I wanted to do
this kind of thing in several places, and so vastly extended my script to
be more general.  It took shape as a proper software package, so I wrote
some docs and examples, bundled it up, gave it a web page, and this is the
end result.


System requirements
--------------------
pmpp has been written in Python (http://www.python.org).  I used Python
1.5.1 to write it, but I think it'll run in 1.4.  A system like GNU make
and/or RCS would also help when using pmpp.  pmpp also makes a few very
small assumptions about your system, namely that GNU install and sed are
installed.


Licensing
----------
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


Download
---------
The current version of pmpp is the development version 0.02.  The latest
"stable" version is 0.01.  This version is "development" mainly because I
haven't updated very much (basically none) of the documentation.  I expect
that soon the configuration file format may change (due mainly to the
inclusion of #include type directives), and so I'm going to hold off on the
docs until then, at which point I'll update the docs heavily.

The pmpp homepage is http://www.zip.com.au/~kev/pmpp/, and you can download
the latest version (v0.02) as a gzipped tar file (19kb) from
http://www.zip.com.au/~kev/pmpp/pmpp-0.02.tar.gz
Olders versions are also available at http://www.zip.com.au/~kev/pmpp/old/


Installation
-------------
* Uncompress the distribution somewhere handy, like /usr/local/src

  tar xzC /usr/local/src -f pmpp-0.01.tar.gz
  cd /usr/local/src/pmpp-0.01

* By default, pmpp will be installed into /usr/local/bin (as pmpp.py and
  pmpp).  If you want to install pmpp into a different directory, edit the
  Makefile in the main distribution directory and change the BINDIR
  variable.

* Ensure that the Python interpreter is in your $PATH and is called python.
  If python is in your $PATH pmpp will automatically find it and configure
  itself to use it.  If you want to make pmpp use a different Python
  interpreter, edit the Makefile and change the PYTHON variable.

* To configure pmpp for your Python interpreter, run 'make'.

* To install pmpp, run 'make install'.

* pmpp is now installed!  You can run it using either 'pmpp.py' or 'pmpp'

* If you want to uninstall pmpp, run

  cd /usr/local/src/pmpp-0.01
  make uninstall


Using pmpp
-----------
pmpp uses config files, template files and possibly header and footer
files.  The config file is the main file, and specifies things like the
template file, header and footer files (if they exist), the output file,
and finally, the articles.  Config files consist of a series of directives,
separated by whitespace and comments.

A comment is a line where the first non-whitespace character is '#' or ';'.
Note that comments halfway through a line aren't supported, that is, a line
is either a directive, comment, or blank (only whitespace).

A directive is a key-value pair, specified by the syntax is 'key=value'.
Whitespace is stripped from both the key and value, so for readability
directives may also be 'key = value' or indented.  Keys are arbitrary
strings not starting with '#' or ';' and not starting or ending with
whitespace (note: whitespace is allowed in the key, but not recommended).
The value is (usually) terminated by the end of the line.  However, if the
first character of the value is a '"', then the value is a multiline value.
This means that the value will continue until a line with a single dot
('.') is found.

A replacement operator is the name of a key (case sensitive) surrounded by
ampersands (&), eg. &color&.  Replacement operators are contained in
template files, and when a replacement operator is encountered in a
template file, it will be removed and replaced with the value associated
with the replacement operators' key, either from the particular article's
directives or the global directives.

The files simple/simple.pmpp and sample/sample.pmpp are two simple, fully
commented examples of pmpp config files (with corresponding template files
simple/simple.tmpl and sample/sample.tmpl).  They describe all the required
directives, and show how to have headers, footers, and so on.

pmpp is run with the names of the config files it is to process as command
line arguments.  For example, if I have a config file called test.pmpp, I
would run that in pmpp with the command:

pmpp test.pmpp

More than one config file can be specified, in which case pmpp will process
the config files independently, one after the other (ie. 'pmpp 1.pmpp
2.pmpp' is equivalent to 'pmpp 1.pmpp ; pmpp 2.pmpp').   The file "-"
indicates that the config file is to be read from standard input, and in
addition if no config files are specified then standard input is assumed.

pmpp works by outputting the header (if any) to the output file, followed
by one or more articles (specified in the config file), followed by the
footer (if any).  Each article is the contents of the template file, with
any replacement operators removed and replaced with the value of the
associated key, as specified in the config file.

Probably the best way to learn how to use pmpp and its various files, after
reading this introduction, is to check out the supplied example pmpp
setups.

The pmpp distribution comes with three example pmpp setups.  These are in
the simple/, sample/ and real/ directories under the main distribution
directory (you should probably look at them in that order, simple/, sample/
and real/).  simple/ is a very simple, trivial example of how to go about
specifying things in config files, and how to go about setting up a
template file.  sample/ is still fairly trivial, but goes into greater
depths and complication, providing text and html output of the same data.
real/ is a more practical, "real-world" example of how to use pmpp, and is
in fact my original use for pmpp (from the Sefton Net Night web page
(http://www.zip.com.au/~kev/snn/)).  Refer to the README files in these
directories for the specific details of each example.

Of course, when all else fails, check out the source (I feel the source
flows strong in you, young Luke).  :)


Author
-------
pmpp was written by Kevin Pulo (kev@zip.com.au, http://www.zip.com.au/~kev/).
Feedback about pmpp is very welcome, especially if you put it to good use!
I'm also on the lookout for good suggestions and bug reports.


Addendum
---------
Re: Python vs. Perl: To those who've seen what pmpp does and think that it
would be better written in perl, yeah I know.  The problem is that I don't
like perl.  :) I'm not fluent in perl, but from what I've seen, I prefer
Python.


