xml-general-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jas...@apache.org
Subject cvs commit: xml-site/sources/xerces-p readme.xml
Date Tue, 07 May 2002 06:11:11 GMT
jasons      02/05/06 23:11:11

  Modified:    sources/xerces-p readme.xml
  Log:
  	* readme.xml (Repository):
  	updated to 1.7.0-1
  	modified to work with readme.xsl
  
  Revision  Changes    Path
  1.9       +268 -241  xml-site/sources/xerces-p/readme.xml
  
  Index: readme.xml
  ===================================================================
  RCS file: /home/cvs/xml-site/sources/xerces-p/readme.xml,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- readme.xml	29 Mar 2002 02:59:41 -0000	1.8
  +++ readme.xml	7 May 2002 06:11:11 -0000	1.9
  @@ -3,179 +3,199 @@
   <!ENTITY % VERSION  SYSTEM "entities.ent">
   %VERSION;
   ]>
  -<s1 title="Xerces Perl">
  -  <s2 title="XML::Xerces &XERCES_P_VERSION;">
  -    <p> XML::Xerces is the Perl API to the Apache project's
  -      Xerces XML parser. It is implemented using the Xerces C++ API, and
  -      it provides access to <em>most</em> of the C++ API from Perl.
  +<s1 title="Xerces Perl: The Perl API to the Apache Xerces XML parser">
  +  <s2 title="Current Release: &XERCES_P_NAME; &XERCES_P_VERSION;">
  +    <p> 
  +&XERCES_P_NAME; is the Perl API to the Apache project's Xerces XML
  +parser. It is implemented using the Xerces C++ API, and it provides
  +access to <em>most</em> of the C++ API from Perl.
  +    </p>
  +    <p> 
  +Because it is based on &XERCES_C_NAME;, &XERCES_P_NAME; provides a
  +validating XML parser that makes it easy to give your application the
  +ability to read and write XML data. A shared library is provided for
  +parsing, generating, manipulating, and validating XML
  +documents. &XERCES_P_NAME; is faithful to the XML 1.0 recommendation
  +and associated standards (DOM 1.0, DOM 2.0. SAX 1.0, SAX 2.0,
  +Namespaces, and Schema). The parser provides high performance,
  +modularity, and scalability. It also provides full support for
  +Unicode.
       </p>
  -
  -    <p> Because it is based on Xerces-C, XML::Xerces provides a validating
  -      XML parser that makes it easy to give your application the
  -      ability to read and write XML data. A shared library is provided
  -      for parsing, generating, manipulating, and validating XML
  -      documents. XML::Xerces is faithful to the XML 1.0 recommendation
  -      and associated standards (DOM 1.0, DOM 2.0. SAX 1.0, SAX 2.0,
  -      Namespaces, and Schema). The parser provides high performance,
  -      modularity, and scalability. It also provides full support for
  -      Unicode.
  -    </p>
  -
  -    <p>XML::Xerces implements the vast majority of the Xerces-C API (if you
  -      notice any discrepancies please mail the <jump
  -       href="mailto:xerces-p-dev@xml.apache.org">list</jump>). The
  -       exception of this are some functions in the C++ API which have
  -       been overloaded to accept different arguments may currently
  -       have only a single version in the Perl API. This is a simple
  -       fix and most of the overloaded functions are finished, but will
  -       take time to catch them all. Also, there are some functions in
  -       the C++ API which either have better Perl counterparts (such as
  -       file I/O) or which manipulate internal C++ information that has
  -       no role in the Perl module.
  -    </p>
  -
  -    <p> The majority of the API is created automatically using <jump
  -       href="http://www.swig.org/">Simplified Wrapper Interface Generator
  -	(SWIG)</jump>. However, care has been taken to make most method
  -      invocations natural to perl programmers, so a number of rough C++
  -      edges have been smoothed over (See the <link
  -       anchor='perl-api'>Special Perl API Features</link> section).
  +    <p>
  +&XERCES_P_NAME; implements the vast majority of the Xerces-C API (if
  +you notice any discrepancies please mail the <jump
  +href="mailto:&XERCES_P_LIST;">list</jump>). The exception
  +of this are some functions in the C++ API which have been overloaded
  +to accept different arguments may currently have only a single version
  +in the Perl API. This is a simple fix and most of the overloaded
  +functions are finished, but will take time to catch them all. Also,
  +there are some functions in the C++ API which either have better Perl
  +counterparts (such as file I/O) or which manipulate internal C++
  +information that has no role in the Perl module.
  +    </p>
  +    <p> 
  +The majority of the API is created automatically using 
  +<jump href="http://www.swig.org/">Simplified Wrapper Interface
  +Generator (SWIG)</jump>.  However, care has been taken to make most
  +method invocations natural to perl programmers, so a number of rough
  +C++ edges have been smoothed over (See the <link
  +anchor='perl-api'>Special Perl API Features</link> section).
       </p>
     </s2>
     <s2 title="Available Platforms">
  -    <p> The code has been tested on the following Unix platforms: </p>
  +    <p>
  +The code has been tested on the following Unix platforms: 
  +    </p>
       <ul>
         <li>Linux</li>
         <li>BSD</li>
         <li>Solaris </li>
       </ul> 
  -    <p>An early version of XML::Xerces (1.3.3) was ported to
  -      Windows. A port is underway, and once completed, Windows will
  -      become a fully supported platform.
  +    <p>
  +An early version of &XERCES_P_NAME; (1.3.3) was ported to Windows. A
  +port is underway, and once completed, Windows will become a fully
  +supported platform.
       </p>
   
     </s2>
     <s2 title="Build Requirements">
       <s3 title="ANSI C++ compiler">
         <p>
  -      Builds are known to work with the GNU
  -      compiler.  Ports to other compilers such as MSVC++ (the Microsoft
  -      Visual C++ compiler and development environment) are in the works.
  -      Contributions in this area are always welcome :-).
  +Builds are known to work with the GNU compiler.  Ports to other
  +compilers such as MSVC++ (the Microsoft Visual C++ compiler and
  +development environment) are in the works.  Contributions in this area
  +are always welcome :-).
         </p>
       </s3>
       <s3 title="Perl5">
  -      <note> <em> Required version: 5.6.0</em></note>
  +      <note>Required version: 5.6.0</note>
         <p>
  -    XML::Xerces now supports Unicode. Since Unicode support wasn't
  -    added to Perl until 5.6.0, you will need to upgrade in order to
  -    use this and future versions of XML::Xerces. Upgrading to at least
  -    to the latest stable release, 5.6.1, is recommended, but if you
  -    already have 5.6.0 installed it will work fine.
  +&XERCES_P_NAME; now supports Unicode. Since Unicode support wasn't
  +added to Perl until 5.6.0, you will need to upgrade in order to use
  +this and future versions of &XERCES_P_NAME;. Upgrading to at least to
  +the latest stable release, 5.6.1, is recommended, but if you already
  +have 5.6.0 installed it will work fine.
         </p>
         <p>
  -    If you plan on using Unicode, I *strongly* recommend upgrading to
  -    Perl-5.7.2, the latest development version. There have been
  -    significant improvements to Perl's Unicode support.
  +If you plan on using Unicode, I <em>strongly</em> recommend upgrading
  +to Perl-5.7.2, the latest development version. There have been
  +significant improvements to Perl's Unicode support.
         </p>
       </s3>
       <s3 title="The Apache Xerces C++ XML Parser">
  -      <note> <em> Required version: &XERCES_C_VERSION;</em></note>
  +      <note>Required version: &XERCES_C_VERSION;</note>
         <p>
  -      (which can be downloaded from: <jump
  -    href="http://xml.apache.org/dist/xerces-c/stable/">
  -        http://xml.apache.org/dist/xerces-c/stable/</jump>
  -      You'll need both the library and header files, and
  -      to set up any environment variables that will direct the
  -      XML::Xerces build to the directories where these reside.
  +(which can be downloaded from <jump href="http://xml.apache.org/dist/xerces-c/stable/">
  +the apache archive</jump>) You'll need both the library and header
  +files, and to set up any environment variables that will direct the
  +&XERCES_P_NAME; build to the directories where these reside.
         </p>
       </s3>
     </s2>
  -  <s2 title="Optional Components">
  -    <p><jump href="http://www.swig.org/"> Simplified Wrapper Interface
  -	Generator (SWIG)</jump> is an open source tool by David Beazley of
  -      the University of Chicago for automatically generating Perl
  -      wrappers for C and C++ libraries (i.e. *.a or *.so for UNIX, *.dll
  -      for Windoes).  You can get the source from <jump
  -       href="http://www.swig.org/">www.swig.org</jump> and then build it
  -      for your platform.
  -    </p>
  -    <p>You will only need this if the include Xerces.C and XML::Xerces
  -      files do not work for your perl distribution. The pre-generated
  -      files have been created by SWIG 1.3 and work under perl-5.005
  -      and perl-5.6.
  -    </p>
  -    <p>
  -      This port will only work with SWIG 1.3.12 (which is currently
  -      only available via CVS).
  -    </p>
  -    <p>
  -      If your planning to use SWIG, you can set the environment variable
  -      SWIG to the full path to the SWIG executable before running <code>perl
  -	Makefile.pl</code>. For example:</p>
  -    <ul>
  -      <li><code>export SWIG=/usr/bin/swig</code></li>
  -    </ul>
  -    <p>
  -      This is only necessary if it isn't in your path or you have more
  -      than one version installed.
  -    </p>
  +  <s2 title="Development Tools">
  +    <note>These are only for internal &XERCES_P_NAME; development. If
  +    your intention is solely to use &XERCES_P_NAME; to write XML
  +    applications in Perl, you will <em>NOT</em> need these
  +    tools.</note>
  +    <s3 title="SWIG">
  +      <p>
  +<jump href="http://www.swig.org/"> Simplified Wrapper Interface
  +Generator (SWIG)</jump> is an open source tool by David Beazley of the
  +University of Chicago for automatically generating Perl wrappers for C
  +and C++ libraries (i.e. *.a or *.so for UNIX, *.dll for Windoes).  You
  +can get the source from <jump
  +href="http://www.swig.org/">the SWIG home page</jump> and then build it for
  +your platform.
  +      </p>
  +      <p>
  +You will only need this if the include Xerces.C and &XERCES_P_NAME;
  +files do not work for your perl distribution. The pre-generated files
  +have been created by SWIG 1.3 and work under perl-5.005 and perl-5.6.
  +      </p>
  +      <p>
  +This port will only work with SWIG 1.3.12 (which is currently only
  +available via CVS).
  +      </p>
  +      <p>
  +If your planning to use SWIG, you can set the environment variable
  +SWIG to the full path to the SWIG executable before running <code>perl
  +Makefile.pl</code>. For example:
  +      </p>
  +      <source><![CDATA[
  +          export SWIG=/usr/bin/swig
  +      ]]></source>
  +      <p>
  +This is only necessary if it isn't in your path or you have more than
  +one version installed.
  +      </p>
  +    </s3>
     </s2>
     <s2 title="Prepare for the build">
  -    <ol>
  -      <li>Download the release and it's digital signature, from
  +    <s3 title="Download &XERCES_P_NAME;">
  +      <p>
  +	Download the release and it's digital signature, from
   	<jump href="http://xml.apache.org/dist/xerces-p/stable">
  -	http://xml.apache.org/dist/xerces-p/stable </jump>.</li>
  -
  -      <li> Optionally verify the release using the supplied digital signature
  -	(see <jump
  +	  the apache Xerces-C archive</jump>.
  +      </p>
  +    </s3>
  +    <s3 title="Verify the archive">
  +      <p>
  +	Optionally verify the release using the supplied digital
  +	signature (see <jump
   	href="http://xml.apache.org/xerces-p/download.html">
  -	http://xml.apache.org/xerces-p/download.html </jump> for
  -	details) </li>
  -
  -      <li>Unpack the archive in a directory of your choice.  Example (for
  -	UNIX):</li>
  +	  the apache Xerces-Perl archive</jump> for details)
  +      </p>
  +    </s3>
  +    <s3 title="Unpack the archive">
  +      <p>
  +	Unpack the archive in a directory of your choice. Example (for
  +	UNIX):
  +      </p>
         <ul>
   	<li><code>tar zxvf XML-Xerces-&XERCES_P_VERSION;.tar.gz</code></li>
   	<li><code>cd XML-Xerces-&XERCES_P_VERSION;</code></li>
  -      </ul> <li>Examine the Perl script "Makefile.PL".  You shouldn't
  -	need to change any of the information unless you are
  -	attempting to build on a platform other than UNIX, in which
  -	case, you will probably have to.
  -	<br/><br/>
  -	Also, you may want to edit the path to the swig executable
  -	($SWIG), if you're planning on regenerating Xerces.C and
  -	XML::Xerces
  -      </li>
  -      <li>If the Xerces-C library and header files are installed on your
  -	system directly, e.g. via an rpm or deb package, proceed to the
  -	build.
  -	<br/><br/>    
  -	Otherwise, you must download Xerces from xml.apache.org and build
  -	it.  To build XML::Xerces in this case, make sure the value of your
  -	XERCESCROOT environment variable is the top-level directory of
  -	your xerces distribution (i.e. the same value it needs to be to
  -	build XERCES).
  -	<br/><br/>
  +      </ul> 
  +    </s3>
  +    <s3 title="Examine Makefile.PL">
  +      <p>
  +	Examine the Perl script "Makefile.PL".  You shouldn't need to
  +	change any of the information unless you are attempting to
  +	build on a platform other than UNIX, in which case, you will
  +	probably have to.
  +      </p>
  +    </s3>
  +    <s3 title="Getting &XERCES_C_NAME;">
  +      <p>
  +	If the Xerces-C library and header files are installed on your
  +	system directly, e.g. via an rpm or deb package, proceed to
  +	the build.
  +      </p>
  +      <p>
  +	Otherwise, you must download Xerces from xml.apache.org and
  +	build it.  To build &XERCES_P_NAME; in this case, make sure
  +	the value of your XERCESCROOT environment variable is the
  +	top-level directory of your xerces distribution (i.e. the same
  +	value it needs to be to build XERCES).
  +      </p>
  +      <p>
   	If you have built Xerces-C yourself and want to work directly from
   	the build directory, then you should only need to set the
   	XERCESCROOT environment variable.
   	If you have installed xerces on your system you should only need
   	to set the XERCES_INCLUDE and XERCES_LIB environment
   	variables. For example:
  -      </li>
  -      <ul>
  -	<li><code>export
  -	    XERCES_INCLUDE=/usr/include/xerces</code></li>
  -	<li><code>export XERCES_LIB=/usr/lib</code></li>
  -      </ul>
  -    </ol>
  +      </p>
  +      <source><![CDATA[
  +	export XERCES_INCLUDE=/usr/include/xerces
  +	export XERCES_LIB=/usr/lib
  +      ]]></source>
  +    </s3>
     </s2>
  -  <s2 title="Build XML::Xerces">
  +  <s2 title="Build &XERCES_P_NAME;">
       <ol>
         <li>Go to the XML-Xerces-&XERCES_P_VERSION; directory.</li>
  -      <li>Build XML::Xerces as you would any perl package that you might get
  -	from CPAN: </li>
  +      <li>Build &XERCES_P_NAME; as you would any perl package that you
  +	might get from CPAN:</li> 
         <ul>
   	<li><code>perl Makefile.PL</code></li>
   	<li><code>make</code></li>	
  @@ -184,56 +204,57 @@
         </ul>
       </ol>
     </s2>
  -  <s2 title="Using XML::Xerces">
  +  <s2 title="Using &XERCES_P_NAME;">
       <p>
  -      XML::Xerces implements the vast majority of the Xerces-C API (if
  -      you notice any discrepancies please mail the
  -      list). Documentation for this API are sadly not available in POD
  -      format, but the Xerces-C html documentation is available at:
  -      <jump href="http://xml.apache.org/xerces-c/apiDocs/index.html">
  -      http://xml.apache.org/xerces-c/apiDocs/index.html </jump></p>
  +&XERCES_P_NAME; implements the vast majority of the Xerces-C API (if
  +you notice any discrepancies please mail the
  +list). Documentation for this API are sadly not available in POD
  +format, but the Xerces-C html documentation is available 
  +<jump href="http://xml.apache.org/xerces-c/apiDocs/index.html">
  +online</jump>.</p>
       <p>
  -      For more information, see the sample scripts: DOMCount.pl,
  -      DOMCreate.pl, and DOMPrint.pl in the samples/ directory, or the test
  -      scripts located in the t/ directory (especially the TestUtils.pm
  -      module).
  +For more information, see the sample scripts: DOMCount.pl,
  +DOMCreate.pl, and DOMPrint.pl in the samples/ directory, or the test
  +scripts located in the t/ directory (especially the TestUtils.pm
  +module).
       </p>
     </s2>
     <s2 title="Special Perl API Features">
  -    <p> Even though XML::Xerces is based on the C++ API, it has been modified in
  -      a few ways to make it more accessible to typical Perl usage,
  -      primarily in the handling:
  -    <anchor name="perl-api"/>
  +    <p>
  +Even though &XERCES_P_NAME; is based on the C++ API, it has been
  +modified in a few ways to make it more accessible to typical Perl
  +usage, primarily in the handling:
       </p>
  +    <p><anchor name="perl-api"/></p>
       <ul>
  -      <li> <link anchor="string">String I/O</link> (Perl strings versus
XMLch arrays)</li>
  -      <li> <link anchor="list">List I/O</link>   (Perl lists versus DOM_NodeList's)</li>
  -      <li> <link anchor="hash">Hash I/O</link>   (Perl hashes versus
DOM_NamedNodeMap's)</li>
  -      <li> <link anchor="serialize">Serialize API</link></li>
  -      <li> <link anchor="handlers">Implementing Perl handlers for C++
  -      event callbacks</link></li>
  -      <li> <link anchor="exceptions">handling C++ exceptions</link></li>
  -      <li> <link anchor="dom_vs_idom">DOM vs. IDOM: Incompatible Change</link></li>
  +      <li><link anchor="string">String I/O</link> (Perl strings versus
XMLch arrays)</li>
  +      <li><link anchor="list">List I/O</link> (Perl lists versus DOM_NodeList's)</li>
  +      <li><link anchor="hash">Hash I/O</link> (Perl hashes versus DOM_NamedNodeMap's)</li>
  +      <li><link anchor="serialize">DOM Serialization API</link></li>
  +      <li><link anchor="handlers">Implementing Perl handlers for C++ event
callbacks</link></li>
  +      <li><link anchor="exceptions">handling C++ exceptions</link></li>
  +      <li><link anchor="dom_vs_idom">DOM vs. IDOM: Incompatible Change</link></li>
       </ul>
       <p><anchor name="string"/></p>
       <s3 title="String I/O">
  -      <p> Any functions in the C++ API that return
  -      <code>XMLCh</code> arrays will return plain vanilla perl-strings in
  -      XML::Xerces.  This obviates calls to <code>transcode</code> (in
  -      fact, it makes them entirely invalid).
  +      <p>
  +Any functions in the C++ API that return <code>XMLCh</code> arrays
  +will return plain vanilla perl-strings in &XERCES_P_NAME;.  This
  +obviates calls to <code>transcode</code> (in fact, it makes them
  +entirely invalid).
         </p>
       </s3>
       <p><anchor name="list"/></p>
       <s3 title="List I/O">
  -      <p>Any function that in the C++ API returns
  -      a <code>DOM_NodeList</code> (<em>e.g.</em>
  -      <code>getChildNodes()</code> and
  -      <code>getElementsByTagName()</code> for example) will return
  -      different types if they are called in a list context or a scalar
  -      context. In a scalar context, these functions return a reference
  -      to a <code>XML::Xerces::DOM_NodeList</code>, just like in C++
  -      API. However, in a list context they will return a Perl list of
  -      <code>XML::Xerces::DOM_Node</code> references. For example:
  +      <p>
  +Any function that in the C++ API returns a <code>DOM_NodeList</code>
  +(e.g.  <code>getChildNodes()</code> and <code>getElementsByTagName()</code>

  +for example) will return different types if they are called in a list
  +context or a scalar context. In a scalar context, these functions
  +return a reference to a <code>XML::Xerces::DOM_NodeList</code>,
  +just like in C++ API. However, in a list context they will return a
  +Perl list of <code>XML::Xerces::DOM_Node</code> references. For
  +example:
         </p>
         <source><![CDATA[
         	# returns a reference to a XML::Xerces::DOM_NodeList
  @@ -242,21 +263,19 @@
         	# returns a list of XML::Xerces::DOM_Node's
         	my @node_list = $doc->getElementsByTagName('foo');
         ]]></source>
  -
       </s3>
       <p><anchor name="hash"/></p>
       <s3 title="Hash I/O">
  -      <p> Any function that in the C++ API
  -      returns a <code>DOM_NamedNodeMap</code>
  -      (<code>getEntities()</code> and <code>getAttributes()</code>
for
  -      example) will return different types if they are called in a
  -      list context or a scalar context. In a scalar context, these
  -      functions return a reference to a
  -      <code>XML::Xerces::DOM_NamedNodeMap</code>, just like in C++
  -      API. However, in a list context they will return a Perl
  -      hash. For example:
  +      <p>
  +Any function that in the C++ API returns a
  +<code>DOM_NamedNodeMap</code> (<code>getEntities()</code> and
  +<code>getAttributes()</code> for example) will return different types
  +if they are called in a list context or a scalar context. In a scalar
  +context, these functions return a reference to a
  +<code>XML::Xerces::DOM_NamedNodeMap</code>, just like in C++
  +API. However, in a list context they will return a Perl hash. For
  +example:
         </p>
  -      
         <source><![CDATA[
         	# returns a reference to a XML::Xerces::DOM_NamedNodeMap
         	my $attr_map_ref = $element_node->getAttributes();
  @@ -267,103 +286,111 @@
       </s3>
       <p><anchor name="serialize"/></p>
       <s3 title="Serialize API">
  -      <p>The XML::Xerces::DOMParse module implements a generic
  -      serializer API for DOM Trees. See the script <link
  -      idref="domprint"> DOMPrint.pl</link> for an example of how to
  -      use the API.
  +      <p>
  +The XML::Xerces::DOMParse module implements a generic serializer API
  +for DOM Trees. See the script <link idref="domprint">
  +DOMPrint.pl</link> for an example of how to use the API.
         </p>
  -      <p>For less complex usage, just use the serialize() method defined for
  -	all DOM_Node subclasses.
  +      <p>
  +For less complex usage, just use the serialize() method defined for
  +all DOM_Node subclasses.
         </p>
       </s3>
       <p><anchor name="handlers"/></p>
  -    <s3 title="Implementing {Document,Content,Error}Handlers from Perl
  -    ">
  -      <p>Thanks to suggestions from Duncan Cameron, XML::Xerces now has a handler
  -	API that matches the currently used semantics of other Perl
  -	XML API's. There are three classes available for application
  -	writers:</p>
  +    <s3 title="Implementing {Document,Content,Error}Handlers from Perl">
  +      <p>
  +Thanks to suggestions from Duncan Cameron, &XERCES_P_NAME; now has a
  +handler API that matches the currently used semantics of other Perl
  +XML API's. There are three classes available for application
  +writers:
  +      </p>
         <ul>
   	<li>PerlErrorHandler    (SAX 1/2 and DOM 1)</li>
   	<li>PerlDocumentHandler (SAX 1)</li>
   	<li>PerlContentHandler  (SAX 2)</li>
         </ul>
  -      <p>Using these classes is as simple as creating a perl subclass of the
  -	needed class, and redefining any needed methods. For example,
  -	to override the default fatal_error() method of the
  -	PerlErrorHandler class we can include this piece of code
  -	within our application:</p>
  +      <p>
  +Using these classes is as simple as creating a perl subclass of the
  +needed class, and redefining any needed methods. For example, to
  +override the default fatal_error() method of the PerlErrorHandler
  +class we can include this piece of code within our application:
  +      </p>
         <source><![CDATA[
  -
  -  package MyErrorHandler;
  -  @ISA = qw(XML::Xerces::PerlErrorHandler);
  -  sub fatal_error {die "Oops, I got an error\n";}
  -  
  -  package main;
  -  my $dom = new XML::Xerces::DOMParser;
  -  $dom->setErrorHandler(MyErrorHandler->new());
  -
  -]]></source>
  +        package MyErrorHandler;
  +        @ISA = qw(XML::Xerces::PerlErrorHandler);
  +        sub fatal_error {die "Oops, I got an error\n";}
  +        
  +        package main;
  +        my $dom = new XML::Xerces::DOMParser;
  +        $dom->setErrorHandler(MyErrorHandler->new());
  +	]]></source>
       </s3>
       <p><anchor name="exceptions"/></p>
       <s3 title="Handling exceptions ({XML,DOM,SAX}Exception's)">
  -      <p>Some errors occur outside parsing and are not caught by the parser's
  -	ErrorHandler. XML::Xerces provides a way for catching these errors using
  -	the PerlExceptionHandler class.
  +      <p>
  +Some errors occur outside parsing and are not caught by the parser's
  +ErrorHandler. &XERCES_P_NAME; provides a way for catching these errors
  +using the PerlExceptionHandler class.
         </p>
         <p>
  -	There are a default methods that prints out an error message and calls
  -	die(), but if more is needed, see the files t/XMLException.t,
  -	t/SAXException.t, and t/DOMException.t for details on how to roll your
  -	own handler.
  +There are a default methods that prints out an error message and calls
  +die(), but if more is needed, see the files t/XMLException.t,
  +t/SAXException.t, and t/DOMException.t for details on how to roll your
  +own handler.
         </p>
       </s3>
       <p><anchor name="dom_vs_idom"/></p>
       <s3 title="DOM vs. IDOM">
         <p><em>Incompatible Change</em></p>
  -      <p>Since Xerces-C-1.5 there has been an experimental DOM implementation
  +      <p>
  +Since Xerces-C-1.5 there has been an experimental DOM implementation
   (IDOM) that is much more efficient than the old DOM implementation. As
  -of XML::Xerces-1.7.0_0 all DOM methods have been switched to the IDOM
  -implementation, and the old DOM implementation is no longer
  -available. </p>
  +of &XERCES_P_NAME;-1.7.0_0 all DOM methods have been switched to the
  +IDOM implementation, and the old DOM implementation is no longer
  +available.
  +      </p>
         <p>
   This has made the codebase much smaller and more efficient, but there
   are some important issues to watch out for, and some code written to
   use the old DOM implementation may not work:
         </p>
         <ul>
  -	<li><code>DOM_Node::isNull()</code>: is no longer
  -	available. In the old DOM API, you could receive a valid
  -	<code>DOM_Node</code> that was really just a wrapper for a
  -	<code>NULL</code> pointer, so before you did anything, you
  -	always had to check it using the <code>isNull()</code>
  -	method. Using the new DOM, you will get <code>undef</code>
  -	instead of an object, so you would instead check using
  -	  <code>defined()</code>.</li>
  -	<li><code>DOMParser::setToCreateXMLDeclTypeNode()</code>: the
  -	  now DOM API follows the W3C specification more closely than
  -	  the old one did, so this method is no longer available.</li>
  -	<li><code>DOM_Document::createDocument()</code>: the now DOM
  -	API follows the W3C specification more closely than the old
  -	one did, so this method is no longer available, use
  -	<code>DOM_DOMImplementation::createDocument()</code>
  -	  instead.</li>
  +	<li><code>DOM_Node::isNull()</code>: is no longer available. In the
old
  +  DOM API, you could receive a valid <code>DOM_Node</code> that was
  +  really just a wrapper for a <code>NULL</code> pointer, so before you
  +  did anything, you always had to check it using the
  +  <code>isNull()</code> method. Using the new DOM, you will get
  +  <code>undef</code> instead of an object, so you would instead check
  +  using <code>defined()</code>.
  +	</li>
  +	<li><code>DOMParser::setToCreateXMLDeclTypeNode()</code>: the now DOM
API
  +  follows the W3C specification more closely than the old one did, so
  +  this method is no longer available.
  +	</li>
  +	<li><code>DOM_Document::createDocument()</code>: the new DOM
  +  API follows the W3C specification more closely than the old
  +  one did, so this method is no longer available, use
  +  <code>DOM_DOMImplementation::createDocument()</code>
  +  instead.
  +	</li>
         </ul>
       </s3>
     </s2>
     <s2 title="Sample Code">
  -    <p> XML::Xerces comes with three sample applications:</p>
  +    <p>
  +&XERCES_P_NAME; comes with a number of sample applications:
  +    </p>
       <ul>
  -      <li> <link idref="saxcount">SAXCount.pl</link>: Uses the SAX
  -      interface to output a count of the number of elements in an XML document</li>
  -      <li> <link idref="sax2count">SAX2Count.pl</link>: Uses the SAX2
  -      interface to output a count of the number of elements in an XML document</li>
  -      <li> <link idref="domcount">DOMCount.pl</link>: Uses the DOM
  -      interface to output a count of the number of elements in an XML document</li>
  -      <li> <link idref="domprint">DOMPrint.pl</link>: Uses the DOM
  -      interface to output a pretty-printed version of an XML file to STDOUT </li>
  -      <li> <link idref="domcreate">DOMCreate.pl</link>: Creates a simple
XML
  -      document using the DOM interface and writes it to STDOUT</li>
  +      <li><link idref="saxcount">SAXCount.pl</link>: Uses the SAX
  +  interface to output a count of the number of elements in an XML document</li>
  +      <li><link idref="sax2count">SAX2Count.pl</link>: Uses the SAX2
  +  interface to output a count of the number of elements in an XML document</li>
  +      <li><link idref="domcount">DOMCount.pl</link>: Uses the DOM
  +  interface to output a count of the number of elements in an XML document</li>
  +      <li><link idref="domprint">DOMPrint.pl</link>: Uses the DOM
  +  interface to output a pretty-printed version of an XML file to STDOUT </li>
  +      <li><link idref="domcreate">DOMCreate.pl</link>: Creates a simple
XML
  +  document using the DOM interface and writes it to STDOUT</li>
       </ul>
     </s2>
   </s1>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org


Mime
View raw message