----------------------------------------------------------------------

There are two parsing modes:

1. Normal mode.  During this mode template objects are constructed
   for the relevant elements and they are added to the structure
   of the page ($webPage).

2. Copy mode.  During this mode no new template objects are constructed
   and everything that is parsed is copied verbatim to the content of
   the current template.

The copy mode is used for parsing WebClass-es (and WebBox-es, which are
a special case of WebClass-es) in order to copy its content for later
processing.  This is due to the fact that a WebClass by itself does not
add anything in the structure of the page.  Only when an object (WebObject)
of this WebClass is declared, the content of the WebClass is parsed in the
normal mode.  This content is reparsed for each WebObject that is declared
in the page.

----------------------------------------------------------------------

Templates include each-other using the element <include>.  For each 
template that is parsed, a new xml_parser is created.  Also, when a 
<WebObject> element is found in a template, then the content of the
corresponding WebClass is parsed as if it was included or pasted in
that place.  A new xml parser is created too, for parsing the content
of the WebClass.

Trick: Since the content of a template or the content of a WebClass
may not be well-formed xml (because often it does not have a single 
root element), before sending it to the xml parser it is enclosed 
in a dummy element, which serves as its root element and which is 
just ignored by the parser. 

Sometimes the xml parser needs to know the name of the file that it
is parsing, in order to display it in error messages, in case that
there are xml errors in the file.  For this reason, the name of the
file that is being parsed is saved in a global array that keeps data
related to each parser.

----------------------------------------------------------------------

The parser reads the templates and constructs an object representation
of the web page that will be displayed.  This is a tree structure where
each object in the tree has the content of a template and references to
other objects that are contained in this template.  For each framework
element like <if>, <repeat>, <webbox> etc. there is an object that
represents it in the structure and which keeps its string content.
It is like a DOM (Document Object Model) for the framework elements.
Most of these objects are inheritors of the class 'Template'.

The Template class has a member variable 'contents' that contains the
string contents of the template.  It may contain references to other
templates as well, which are marked like this: '&&tpl_id;;', where tpl_id
is the id of the template that is linked (or referenced) in this place.  

When the parser is parsing a template (e.g. a file), whatever string that
it finds is appended to the content of the current_template object.
When if finds a framework element that indicates that a new object must
be created, then it creates a new template object, pushes the current
template in a stack, makes the new template as current, and continues
parsing.  Now whatever is parsed is appended to the new template object.
Once it is done (indicated by a closing tag, e.g. </if>), then the 
previous template (which is not finished yet) is poped from the stack
and made current_template, a reference from the previous template to 
the new template is added and the new template is added in the page
structure, then the parsing of the previous template continues.
 
----------------------------------------------------------------------