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 Mon, 09 Jul 2001 05:15:36 GMT
jasons      01/07/08 22:15:36

  Modified:    sources/xerces-p readme.xml
  Log:
  	* readme.xml (Repository):
  	Now matches README from distribution
  
  Revision  Changes    Path
  1.5       +248 -37   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.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- readme.xml	2001/03/27 05:48:38	1.4
  +++ readme.xml	2001/07/09 05:15:36	1.5
  @@ -1,39 +1,195 @@
   <?xml version="1.0" standalone="no"?>
   <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
   
  -<s1 title="Xerces Perl">
  -  <p> The Xerces Perl project has created a Perl module,
  -  <em>Xerces.pm</em>, as the Perl API to the Apache project's Xerces
  -  XML parser. It is implemented using the Xerces C++ API, and it
  -  provides access to all of the C++ API from Perl.
  -  </p>
  -
  -  <p> Because it is based on Xerces-C, Xerces.pm 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 and
  -  associated standards ( DOM 1.0, DOM 2.0. SAX 1.0, SAX 2.0,
  -  Namespaces), The parser provides high performance, modularity, and
  -  scalability. Source code, samples and API documentation are provided
  -  with the parser.
  -  </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 title="Xerces.pm version 1.3">
  -    <p> This is the first fully-featured release of Xerces.pm. It
  -    provides access to <em>all</em> functionality in the Xerces-C 1.3
  -    API. 
  +<s1 title="Xerces.pm: The Perl API to the Apache Xerces XML parser">
  +  <s2 title="Xerces.pm 1.5.0">
  +    <p> This module implements 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
  +      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
  +      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.
  +    </p>
  +
  +    <p>Xerces.pm 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.
  +    </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>
  +    <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).
  +    </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>
  +  </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 Xerces.pm
  +      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.
  +    </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>
  +  <s2 title="Prepare for the build">
  +    <ol>
  +      <li>Unpack the archive in a directory of your choice.  Example (for
  +	UNIX):</li>
  +      <ul>
  +	<li><code>cd &lt;DIRECTORY OF YOUR CHOICE&gt;</code></li>
  +	<li><code>tar xvf &lt;DIRECTORY Xerces-1.5.x.tar.gz IS
  +	    LOCATED&gt;/Xerces-1.5.x.tar.gz</code></li>
  +      </ul>
  +      <li>Go to the Xerces-1.5.x directory:</li>
  +      <ul>
  +	<li><code>cd Xerces-1.5.x</code></li>
  +      </ul>
  +      <li>Examine the Perl script "Makefile.PL".  You may need to change
  +	some locations of libraries and include directories. If you
  +	attempt to build on a platform other than UNIX, you will probably
  +	have to change more.
  +	<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
  +      </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
  +	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/>
  +	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>
     </s2>
  +  <s2 title="Build Xerces.pm">
  +    <ol>
  +      <li>Go to the Xerces-1.5.x directory.</li>
  +      <li>Build Xerces.pm 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>	
  +	<li><code>make test</code></li>	
  +	<li><code>make install</code></li>	
  +      </ul>
  +    </ol>
  +  </s2>
  +  <s2 title="Using Xerces.pm">
  +    <p>
  +      Xerces.pm 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>
  +    <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).
  +    </p>
  +  </s2>
     <s2 title="Special Perl API Features">
  -    <p> Special handling has been provided for certain functions:
  +    <p> Even though Xerces.pm 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>
  @@ -41,10 +197,13 @@
         <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>
  +      <li> <link anchor="exceptions">handling C++ exceptions</link></li>
       </ul>
  -
  +    <p><anchor name="string"/></p>
       <s3 title="String I/O">
  -      <p><anchor name="string"/>Note that the creation of
  +      <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>
   
  @@ -71,8 +230,9 @@
         fact, it makes them entirely invalid).
         </p>
       </s3>
  +    <p><anchor name="list"/></p>
       <s3 title="List I/O">
  -      <p><anchor name="list"/>Any function that in the C++ API returns
  +      <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
  @@ -91,8 +251,9 @@
         ]]></source>
   
       </s3>
  +    <p><anchor name="hash"/></p>
       <s3 title="Hash I/O">
  -      <p><anchor name="hash"/> Any function that in the C++ API
  +      <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
  @@ -111,21 +272,71 @@
         	my %attrs = $element_node->getAttributes();
         ]]></source>
       </s3>
  +    <p><anchor name="serialize"/></p>
       <s3 title="Serialize API">
  -      <p><anchor name="serialize"/> The XML::Xerces::DOMParse module implements
a generic
  +      <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>
  +    </s3>
  +    <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
  +	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>
  +      <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>
  +    </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. Xerces.pm 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.
  +      </p>
       </s3>
     </s2>
     <s2 title="Sample Code">
       <p> Xerces.pm comes with three sample applications:</p>
       <ul>
  -      <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="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>
  
  
  

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