==================================================
XML PreProcessor (XPP) v0.9 Programmer's Reference
==================================================


1. Writting the input files
---------------------------
You should check out the examples in order to get a basic notion of XPP input file syntax.
If you need to use characters with a special XPP meaning in the input file in order
not to understand them as XPP delimiters, escape them with a backslash \,
i.e. \{ \} \^ \% \|

You can use any XML markup in the input file.
It will remain unchanged in the output,
so you can mix the XPP syntax with the normal XML markup.

The main constructs are (see example 1):
---------------------------------------------

	%element_name element_attrs { element_body }

This construct produces XML element with the "element_name"
and attributes "element_attrs" and content "element_body".
The elements can be nested.
For using the { } % chars in other than this meaning, see above.
---------------------------------------------

	|element_name element_attrs|

This construct produces empty XML element with the "element_name"
and attributes "element_attrs".
For using the | chars in other than this meaning, see above.
---------------------------------------------

	%%element_name

This construct produces empty XML element with the "element_name"
and no attributes.
For using the % chars in other than this meaning, see above.
---------------------------------------------

	#-- comment text

This construct produces XML comment with the content "comment text".
The comment ends at the (CR)LF.
If you need comments that span more lines, use normal XML comment syntax
<!-- comment text ... -->.
---------------------------------------------

	##-- XSLT comment text

This construct produces XSLT comment with the content "XSLT comment text".
The comment ends at the (CR)LF.
If you need comments that span more lines, use XSLT comment element
<xsl:comment>. You can of course, write it as %comment {XSLT comment text}.
---------------------------------------------

Note: The "element_name" can be modified by followinf modifiers:

a) The 'class' attribute specification (see the "tr.secondrow" in the example 1)

b) The 'id' or 'name' attribute specification (see the "tr.firstrow" in the example 1)

c) The 'match' attribute specification on XSLT template element
   (see the "tr.secondrow" in the example 2 - construct '%match/body')

These modifiers can be used with any elements written with all %, ||, %% shortcuts.
Note, however, that they values of the modifiers cannot contain whitespaces.
So if you need the whitespaces (which is unlikely),
write the 'id', 'class' and 'match' attrs via
normal XPP attribute specification.

=============================================
Example 1 (part of "in1.xpt"):
=============================================
%body{
	%h1{%center{The Super Page}}

	|hr width="50%" align="center"|

	%table.nice border="1"{

		%tr#firstrow align="\{in curly brackets\}" width="100\%" { %th{Row1} %td{Row1 value}}

		%tr.secondrow { %th{Row2} %td{Row2 value}}

		%tr{ %th{Row3} %td{Row3 value}}

		#-- xml comment till the (CR)LF
	}
	%h2{First smaller (H2) heading}
	%%hr
	%h2{Second smaller (H2) heading}
}

=============================================
Example 2 (part of "in2.xpt"):
=============================================
%match/body {
	%body{
		%%hr
		%table.nice border="1"{
			%tr#firstrow { %th{RemoteAddr} %td{^$param1^}}
			%tr.secondrow { %th{ServerName} %td{^$param2^}}
			%tr{ %th{Secure} %td{^$param3^}}
		}
		%%apply/*
		%%hr
	}
}
=============================================

(to be finished...)


2. Writting the template files
------------------------------
a) A template is a file serving as a base for producing XPP output.
   The output will contain the template content with the variables
   $template and $encoding replaced with the actual result of the
   input file preprocessing, or with the value of the "encoding"
   variable (see the "xpp.pl" source), respectively.

b) The template does not have to be a well-formed XML file.

c) No escaping in the template is required (and allowed)
   - be aware of the $body and $encoding variables.

(to be finished...)



3. Limitations
--------------
a) If there were some entities that are internaly used by XPP when
   dealing with escaped characters (namely &#37; &#166; &#94; &#123; &#124; ),
   they will be replaced with their normal character representation, i.e. % | ^ { }
   However, since this case is probably rare, and the results should not be
   harmfull, I do not plan to make some workarounds now.


4. Examples
-----------
Please, see the files in the "examples" directory.
For instructions for running the examples, see the readme.txt.
You can also have a look to the "templates" directory for examples on how the templates are created.
Note, however, that the set of examples is not yet complete at all.