--- /dev/null
+<HTML
+><HEAD
+><TITLE
+>Details of the mapping from XML text to the tree representation</TITLE
+><META
+NAME="GENERATOR"
+CONTENT="Modular DocBook HTML Stylesheet Version 1.46"><LINK
+REL="HOME"
+TITLE="The PXP user's guide"
+HREF="index.html"><LINK
+REL="UP"
+TITLE="The objects representing the document"
+HREF="c893.html"><LINK
+REL="PREVIOUS"
+TITLE="The class type extension"
+HREF="x1439.html"><LINK
+REL="NEXT"
+TITLE="Configuring and calling the parser"
+HREF="c1567.html"><LINK
+REL="STYLESHEET"
+TYPE="text/css"
+HREF="markup.css"></HEAD
+><BODY
+CLASS="SECT1"
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#840084"
+ALINK="#0000FF"
+><DIV
+CLASS="NAVHEADER"
+><TABLE
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TH
+COLSPAN="3"
+ALIGN="center"
+>The PXP user's guide</TH
+></TR
+><TR
+><TD
+WIDTH="10%"
+ALIGN="left"
+VALIGN="bottom"
+><A
+HREF="x1439.html"
+>Prev</A
+></TD
+><TD
+WIDTH="80%"
+ALIGN="center"
+VALIGN="bottom"
+>Chapter 3. The objects representing the document</TD
+><TD
+WIDTH="10%"
+ALIGN="right"
+VALIGN="bottom"
+><A
+HREF="c1567.html"
+>Next</A
+></TD
+></TR
+></TABLE
+><HR
+ALIGN="LEFT"
+WIDTH="100%"></DIV
+><DIV
+CLASS="SECT1"
+><H1
+CLASS="SECT1"
+><A
+NAME="AEN1496"
+>3.4. Details of the mapping from XML text to the tree representation</A
+></H1
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1498"
+>3.4.1. The representation of character-free elements</A
+></H2
+><P
+>If an element declaration does not allow the element to
+contain character data, the following rules apply.</P
+><P
+>If the element must be empty, i.e. it is declared with the
+keyword <TT
+CLASS="LITERAL"
+>EMPTY</TT
+>, the element instance must be effectively
+empty (it must not even contain whitespace characters). The parser guarantees
+that a declared <TT
+CLASS="LITERAL"
+>EMPTY</TT
+> element does never contain a data
+node, even if the data node represents the empty string.</P
+><P
+>If the element declaration only permits other elements to occur
+within that element but not character data, it is still possible to insert
+whitespace characters between the subelements. The parser ignores these
+characters, too, and does not create data nodes for them.</P
+><DIV
+CLASS="FORMALPARA"
+><P
+><B
+>Example. </B
+>Consider the following element types:
+
+<PRE
+CLASS="PROGRAMLISTING"
+><!ELEMENT x ( #PCDATA | z )* >
+<!ELEMENT y ( z )* >
+<!ELEMENT z EMPTY></PRE
+>
+
+Only <TT
+CLASS="LITERAL"
+>x</TT
+> may contain character data, the keyword
+<TT
+CLASS="LITERAL"
+>#PCDATA</TT
+> indicates this. The other types are character-free. </P
+></DIV
+><P
+>The XML term
+
+<PRE
+CLASS="PROGRAMLISTING"
+><x><z/> <z/></x></PRE
+>
+
+will be internally represented by an element node for <TT
+CLASS="LITERAL"
+>x</TT
+>
+with three subnodes: the first <TT
+CLASS="LITERAL"
+>z</TT
+> element, a data node
+containing the space character, and the second <TT
+CLASS="LITERAL"
+>z</TT
+> element.
+In contrast to this, the term
+
+<PRE
+CLASS="PROGRAMLISTING"
+><y><z/> <z/></y></PRE
+>
+
+is represented by an element node for <TT
+CLASS="LITERAL"
+>y</TT
+> with only
+<I
+CLASS="EMPHASIS"
+>two</I
+> subnodes, the two <TT
+CLASS="LITERAL"
+>z</TT
+> elements. There
+is no data node for the space character because spaces are ignored in the
+character-free element <TT
+CLASS="LITERAL"
+>y</TT
+>.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1521"
+>3.4.2. The representation of character data</A
+></H2
+><P
+>The XML specification allows all Unicode characters in XML
+texts. This parser can be configured such that UTF-8 is used to represent the
+characters internally; however, the default character encoding is
+ISO-8859-1. (Currently, no other encodings are possible for the internal string
+representation; the type <TT
+CLASS="LITERAL"
+>Pxp_types.rep_encoding</TT
+> enumerates
+the possible encodings. Principially, the parser could use any encoding that is
+ASCII-compatible, but there are currently only lexical analyzers for UTF-8 and
+ISO-8859-1. It is currently impossible to use UTF-16 or UCS-4 as internal
+encodings (or other multibyte encodings which are not ASCII-compatible) unless
+major parts of the parser are rewritten - unlikely...)</P
+><P
+>The internal encoding may be different from the external encoding (specified
+in the XML declaration <TT
+CLASS="LITERAL"
+><?xml ... encoding="..."?></TT
+>); in
+this case the strings are automatically converted to the internal encoding.</P
+><P
+>If the internal encoding is ISO-8859-1, it is possible that there are
+characters that cannot be represented. In this case, the parser ignores such
+characters and prints a warning (to the <TT
+CLASS="LITERAL"
+>collect_warning</TT
+>
+object that must be passed when the parser is called).</P
+><P
+>The XML specification allows lines to be separated by single LF
+characters, by CR LF character sequences, or by single CR
+characters. Internally, these separators are always converted to single LF
+characters.</P
+><P
+>The parser guarantees that there are never two adjacent data
+nodes; if necessary, data material that would otherwise be represented by
+several nodes is collapsed into one node. Note that you can still create node
+trees with adjacent data nodes; however, the parser does not return such trees.</P
+><P
+>Note that CDATA sections are not represented specially; such
+sections are added to the current data material that being collected for the
+next data node.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1532"
+>3.4.3. The representation of entities within documents</A
+></H2
+><P
+><I
+CLASS="EMPHASIS"
+>Entities are not represented within
+documents!</I
+> If the parser finds an entity reference in the document
+content, the reference is immediately expanded, and the parser reads the
+expansion text instead of the reference.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1536"
+>3.4.4. The representation of attributes</A
+></H2
+><P
+>As attribute
+values are composed of Unicode characters, too, the same problems with the
+character encoding arise as for character material. Attribute values are
+converted to the internal encoding, too; and if there are characters that
+cannot be represented, these are dropped, and a warning is printed.</P
+><P
+>Attribute values are normalized before they are returned by
+methods like <TT
+CLASS="LITERAL"
+>attribute</TT
+>. First, any remaining entity
+references are expanded; if necessary, expansion is performed recursively.
+Second, newline characters (any of LF, CR LF, or CR characters) are converted
+to single space characters. Note that especially the latter action is
+prescribed by the XML standard (but <TT
+CLASS="LITERAL"
+></TT
+> is not converted
+such that it is still possible to include line feeds into attributes).</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1542"
+>3.4.5. The representation of processing instructions</A
+></H2
+><P
+>Processing instructions are parsed to some extent: The first word of the
+PI is called the target, and it is stored separated from the rest of the PI:
+
+<PRE
+CLASS="PROGRAMLISTING"
+><?target rest?></PRE
+>
+
+The exact location where a PI occurs is not represented (by default). The
+parser puts the PI into the object that represents the embracing construct (an
+element, a DTD, or the whole document); that means you can find out which PIs
+occur in a certain element, in the DTD, or in the whole document, but you
+cannot lookup the exact position within the construct.</P
+><P
+>If you require the exact location of PIs, it is possible to
+create extra nodes for them. This mode is controled by the option
+<TT
+CLASS="LITERAL"
+>enable_pinstr_nodes</TT
+>. The additional nodes have the node type
+<TT
+CLASS="LITERAL"
+>T_pinstr <TT
+CLASS="REPLACEABLE"
+><I
+>target</I
+></TT
+></TT
+>, and are created
+from special exemplars contained in the <TT
+CLASS="LITERAL"
+>spec</TT
+> (see
+pxp_document.mli).</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1551"
+>3.4.6. The representation of comments</A
+></H2
+><P
+>Normally, comments are not represented; they are dropped by
+default. However, if you require them, it is possible to create
+<TT
+CLASS="LITERAL"
+>T_comment</TT
+> nodes for them. This mode can be specified by the
+option <TT
+CLASS="LITERAL"
+>enable_comment_nodes</TT
+>. Comment nodes are created from
+special exemplars contained in the <TT
+CLASS="LITERAL"
+>spec</TT
+> (see
+pxp_document.mli). You can access the contents of comments through the
+method <TT
+CLASS="LITERAL"
+>comment</TT
+>.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1558"
+>3.4.7. The attributes <TT
+CLASS="LITERAL"
+>xml:lang</TT
+> and
+<TT
+CLASS="LITERAL"
+>xml:space</TT
+></A
+></H2
+><P
+>These attributes are not supported specially; they are handled
+like any other attribute.</P
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="AEN1563"
+>3.4.8. And what about namespaces?</A
+></H2
+><P
+>Currently, there is no special support for namespaces.
+However, the parser allows it that the colon occurs in names such that it is
+possible to implement namespaces on top of the current API.</P
+><P
+>Some future release of PXP will support namespaces as built-in
+feature...</P
+></DIV
+></DIV
+><DIV
+CLASS="NAVFOOTER"
+><HR
+ALIGN="LEFT"
+WIDTH="100%"><TABLE
+WIDTH="100%"
+BORDER="0"
+CELLPADDING="0"
+CELLSPACING="0"
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+><A
+HREF="x1439.html"
+>Prev</A
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="index.html"
+>Home</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+><A
+HREF="c1567.html"
+>Next</A
+></TD
+></TR
+><TR
+><TD
+WIDTH="33%"
+ALIGN="left"
+VALIGN="top"
+>The class type <TT
+CLASS="LITERAL"
+>extension</TT
+></TD
+><TD
+WIDTH="34%"
+ALIGN="center"
+VALIGN="top"
+><A
+HREF="c893.html"
+>Up</A
+></TD
+><TD
+WIDTH="33%"
+ALIGN="right"
+VALIGN="top"
+>Configuring and calling the parser</TD
+></TR
+></TABLE
+></DIV
+></BODY
+></HTML
+>
\ No newline at end of file
projects / helm.git / blobdiff