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 releases.xml
Date Fri, 29 Mar 2002 02:59:41 GMT
jasons      02/03/28 18:59:41

  Modified:    sources/xerces-p readme.xml releases.xml
  Log:
  new version
  
  Revision  Changes    Path
  1.8       +113 -92   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.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- readme.xml	9 Jul 2001 18:09:16 -0000	1.7
  +++ readme.xml	29 Mar 2002 02:59:41 -0000	1.8
  @@ -1,30 +1,37 @@
   <?xml version="1.0" standalone="no"?>
  -<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
  -
  +<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd" [
  +<!ENTITY % VERSION  SYSTEM "entities.ent">
  +%VERSION;
  +]>
   <s1 title="Xerces Perl">
  -  <s2 title="Xerces.pm 1.5.1">
  -    <p> Xerces.pm is the Perl API to the Apache project's
  +  <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.
       </p>
   
  -    <p> Because it is based on Xerces-C, Xerces.pm provides a validating
  +    <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. Xerces.pm is faithful to the XML 1.0 recommendation
  +      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.
  +      Namespaces, and Schema). The parser provides high performance,
  +      modularity, and scalability. It also provides full support for
  +      Unicode.
       </p>
   
  -    <p>Xerces.pm implements the vast majority of the Xerces-C API (if you
  +    <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 is functions in the C++ API which have been
  -      overloaded to accept different arguments, currently have only a
  -      single version in the Perl API. This is a simple fix, but will
  -      take time.
  +       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
  @@ -39,49 +46,50 @@
       <p> The code has been tested on the following Unix platforms: </p>
       <ul>
         <li>Linux</li>
  -      <ul>
  -	<li>PPC-debian: works jason</li>
  -	<li>x86-debian: works harmon</li>
  -	<li>x86-redhat6.2: works jason</li>
  -	<li>x86-redhat7: works jason (recompile Xerces-C and
  -	Perl-5.6.1 from source)</li>
  -      </ul>
         <li>BSD</li>
  -      <ul>
  -	<li>NetBSD (egcs-2.91.66, works: Emanuel Dreyfus
  -	&lt;p99dreyf@criens.u-psud.fr&gt;)</li>
  -	</ul>
         <li>Solaris </li>
  -      <ul>
  -	<li>Solaris 8: works cc and gcc (recompile perl and Xerces-C from source)</li>
  -	<li>Solaris 5.6: works gcc</li>
  -      </ul>
  -    </ul>
  -    <p>Windows is currently not supported. However, minimal changes would be
  -      necessary to enable functionality under Windows (modification of
  -      some Unix 'make' specific code in Makefile.PL).
  +    </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>
  +
     </s2>
     <s2 title="Build Requirements">
  -    <ol>
  -      <li>An ANSI C++ compiler.  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 :-).
  -      </li>
  -      <li>Perl5 (Xerces.pm has been tested with perl 5.005 and 5.6).
  -	Currently only tested on XML documents that are encoded in plain
  -	old ASCII.
  -      </li>
  -      <li>The Apache Xerces C++ XML Parser version 1.5 (which can be
  -	downloaded from: <jump
  -	href="http://xml.apache.org/dist/xerces-c/stable/">http://xml.apache.org/dist/xerces-c/stable/</jump>
  -	<br/><br/>
  -	You'll need both the library and header files, and to set up any
  -	environment variables that will direct the Xerces.pm build to the
  -	directories where these reside.
  -      </li>
  -    </ol>
  +    <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 :-).
  +      </p>
  +    </s3>
  +    <s3 title="Perl5">
  +      <note> <em> Required version: 5.6.0</em></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.
  +      </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.
  +      </p>
  +    </s3>
  +    <s3 title="The Apache Xerces C++ XML Parser">
  +      <note> <em> Required version: &XERCES_C_VERSION;</em></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.
  +      </p>
  +    </s3>
     </s2>
     <s2 title="Optional Components">
       <p><jump href="http://www.swig.org/"> Simplified Wrapper Interface
  @@ -92,13 +100,14 @@
          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 Xerces.pm
  +    <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 is know to work with versions 1.1p5 and 1.3a5 of SWIG.
  +      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
  @@ -127,8 +136,8 @@
         <li>Unpack the archive in a directory of your choice.  Example (for
   	UNIX):</li>
         <ul>
  -	<li><code>tar zxvf XML-Xerces-1.5.x.tar.gz</code></li>
  -	<li><code>cd XML-Xerces-1.5.x</code></li>
  +	<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
  @@ -136,14 +145,14 @@
   	<br/><br/>
   	Also, you may want to edit the path to the swig executable
   	($SWIG), if you're planning on regenerating Xerces.C and
  -	Xerces.pm
  +	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 Xerces.pm in this case, make sure the value of your
  +	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).
  @@ -162,10 +171,10 @@
         </ul>
       </ol>
     </s2>
  -  <s2 title="Build Xerces.pm">
  +  <s2 title="Build XML::Xerces">
       <ol>
  -      <li>Go to the XML-Xerces-1.5.x directory.</li>
  -      <li>Build Xerces.pm as you would any perl package that you might get
  +      <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>
         <ul>
   	<li><code>perl Makefile.PL</code></li>
  @@ -175,9 +184,9 @@
         </ul>
       </ol>
     </s2>
  -  <s2 title="Using Xerces.pm">
  +  <s2 title="Using XML::Xerces">
       <p>
  -      Xerces.pm implements the vast majority of the Xerces-C API (if
  +      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:
  @@ -191,46 +200,26 @@
       </p>
     </s2>
     <s2 title="Special Perl API Features">
  -    <p> Even though Xerces.pm is based on the C++ API, it has been modified in
  +    <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>
       <ul>
  -      <li> <link anchor="string">String I/O</link> (Perl strings versus
DOMString's, XMLch *'s)</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">Serialize API</link></li>
         <li> <link anchor="handlers">Implementing Perl handlers for C++
  -      even callbacks</link></li>
  +      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>Note that the creation of
  -      <code>DOMString</code>'s as arguments to to functions is
  -      optional.  That is, where in C++ you'd have to use:</p>
  -
  -      <source><![CDATA[
  -        document.createElement( new DOMString("foo") );
  -      ]]></source>
  -
  -      in Xerces.pm, you can use either of:
  -
  -      <source><![CDATA[
  -        $document->createElement( XML::Xerces::DOMString->new('foo') );
  -      ]]></source>
  -
  -      or the less cumbersome:
  -
  -      <source><![CDATA[
  -        $document->createElement('foo');
  -      ]]></source>
  -
  -      <p> As well, any functions in the C++ API that return
  -      string-like values, i.e. like <code>DOMString</code>'s and
  -      <code>XMLCh</code> arrays, return plain vanilla perl-strings in
  -      Xerces.pm.  This obviates calls to <code>transcode</code> (in
  +      <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>
       </s3>
  @@ -290,7 +279,7 @@
       <p><anchor name="handlers"/></p>
       <s3 title="Implementing {Document,Content,Error}Handlers from Perl
       ">
  -      <p>Thanks to suggestions from Duncan Cameron, Xerces.pm now has a handler
  +      <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>
  @@ -319,7 +308,7 @@
       <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. Xerces.pm provides a way for catching these errors using
  +	ErrorHandler. XML::Xerces provides a way for catching these errors using
   	the PerlExceptionHandler class.
         </p>
         <p>
  @@ -329,9 +318,41 @@
   	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
  +(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>
  +      <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>
  +      </ul>
  +    </s3>
     </s2>
     <s2 title="Sample Code">
  -    <p> Xerces.pm comes with three sample applications:</p>
  +    <p> XML::Xerces comes with three 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>
  
  
  
  1.2       +17 -1     xml-site/sources/xerces-p/releases.xml
  
  Index: releases.xml
  ===================================================================
  RCS file: /home/cvs/xml-site/sources/xerces-p/releases.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- releases.xml	27 Mar 2001 05:48:52 -0000	1.1
  +++ releases.xml	29 Mar 2002 02:59:41 -0000	1.2
  @@ -1,7 +1,23 @@
   <?xml version="1.0" standalone="no"?>
  -<!DOCTYPE changes SYSTEM "sbk:/style/dtd/changes.dtd">
  +<!DOCTYPE changes SYSTEM "sbk:/style/dtd/changes.dtd" [
  +]>
   
   <changes title="Xerces Perl Releases">
  +  <release version="XML-Xerces-1.7.0_0" date="Mar 24, 2002">
  +    <features>
  +      <feat>Mirrors Xerces-C-1.7.0 release</feat>
  +      <feat> The DOM API is now implemented by the Xerces-C IDOM
  +          implementation (see README for issues)</feat>
  +      <feat>All dynamic casting of DOM_Node*'s is now done internally by
  +          the C++ code. This means that calls to DOM_Node::actual_cast
  +          are now unnecessary.</feat>
  +    </features>
  +    <fixes>
  +      <fix>ensured that methods which return DOM_NodeList's and
  +	  DOM_NamedNodeMap's will never return undef in an array
  +          context (instead they return the empty list).</fix>
  +    </fixes>
  +  </release>
     <release version="XML-Xerces-1.3.3" date="Mar 22, 2001">
       <features>
         <feat> XML::Xerces now has three non-exported functions that can be
  
  
  

---------------------------------------------------------------------
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