docs/install.xml

<?xml version='1.0' encoding='UTF-8'?>
<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->
<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
<s1 title='Installation'>
 <s2 title='Unpacking the Files'>
  <p>
   &ParserName; is packaged as a ZIP file for all platforms 
   and operating systems. The parser release is also packaged
   as Tar GZip files as a convenience for UNIX users. You can
   extract the ZIP files using the Java <ref>jar</ref> command
   to unpack the distribution.
  </p>
  <source>jar xf &ParserName;-bin.&parserversion;.zip
jar xf &ParserName;-src.&parserversion;.zip
jar xf &ParserName;-tools.&parserversion;.zip</source>
  <p>
   All of these commands create a sub-directory called
   "&parserdir;" in the current directory, except for the command to unpack
   the &quot;tools&quot; distribution, since you may install this anywhere you like.
  </p>
 </s2>
 <s2 title='Files in the Binary Package'>
  <table>
   <tr>
    <td>LICENSE</td>
    <td>License for &ParserName;</td>
   </tr>
   <tr>
    <td>NOTICE</td>
    <td>NOTICE file for &ParserName;</td>
   </tr>
   <tr>
    <td>LICENSE.resolver.txt</td>
    <td>License for the XML Commons Resolver</td>
   </tr>
   <tr>
    <td>NOTICE.resolver.txt</td>
    <td>NOTICE file for the XML Commons Resolver</td>
   </tr>
   <tr>
    <td>LICENSE.serializer.txt</td>
    <td>License for the Apache Xalan serializer</td>
   </tr>
   <tr>
    <td>NOTICE.serializer.txt</td>
    <td>NOTICE file for the Apache Xalan serializer</td>
   </tr>
   <tr>
    <td>LICENSE-SAX.html</td>
    <td>SAX License</td>
   </tr>
   <tr>
    <td>LICENSE.DOM-documentation.html</td>
    <td>W3C Document License</td>
   </tr>
   <tr>
    <td>LICENSE.DOM-software.html</td>
    <td>W3C Software License</td>
   </tr>
   <tr>
    <td>Readme.html</td>
    <td>Web page redirect to docs/html/index.html</td>
   </tr>
   <tr>
    <td>resolver.jar</td>
    <td>Jar file containing the XML Commons Resolver. Currently
    Resolver 1.2 is distributed with &ParserName;.</td>
   </tr>
   <tr>
    <td>serializer.jar</td>
    <td>Jar file containing the Apache Xalan serializer. Currently
    the serializer included in Xalan 2.7.1 is distributed with &ParserName;.</td>
   </tr>
   <tr>
    <td>xercesImpl.jar</td>
    <td>Jar file containing all the parser class files that implement
    one of the standard APIs supported by the parser</td>
   </tr>
   <tr>
    <td>xml-apis.jar</td>
    <td>Jar file containing all the standard APIs implemented by
    the parser.  Currently &ParserName; supports DOM level 3, SAX
    2.0.2, and the <code>javax.xml.datatype</code>, 
    <code>javax.xml.parsers</code> and <code>javax.xml.validation</code> 
    parts of JAXP 1.3.</td>
   </tr>
   <tr>
    <td>xercesSamples.jar</td>
    <td>Jar file containing all sample class files</td>
   </tr>
   <tr>
    <td>data/</td>
    <td>Directory containing sample XML data files</td>
   </tr>
   <tr>
    <td>docs/</td>
    <td>Directory containing documentation</td>
   </tr>
   <tr>
    <td>docs/javadocs/</td>
    <td>Directory containing Javadoc API for parser framework</td>
   </tr>
   <tr>
    <td>samples/</td>
    <td>Directory containing the source code for the samples</td>
   </tr>
  </table>
  <note>
   To use &ParserName; you do not need the source files. 
   However, if you want to recompile the sources you need to
   download the source package and have the contents of the tools
   package (or equivalent) available.
  </note>
  <note>
    xerces.jar is no longer available in the main distribution. You can still 
    download this jar from deprecated distribution. xerces.jar is a Jar file 
    that contains all the parser class files (i.e., it contains
    the intersection of the contents of xercesImpl.jar and xml-apis.jar). 
   </note>
 </s2>
 <s2 title='Files in the Source Package'>
  <table>
   <tr>
    <td>LICENSE</td>
    <td>License for &ParserName;</td>
   </tr>
   <tr>
    <td>NOTICE</td>
    <td>NOTICE file for &ParserName;</td>
   </tr>
   <tr>
    <td>LICENSE.resolver.txt</td>
    <td>License for the XML Commons Resolver</td>
   </tr>
   <tr>
    <td>NOTICE.resolver.txt</td>
    <td>NOTICE file for the XML Commons Resolver</td>
   </tr>
   <tr>
    <td>LICENSE.serializer.txt</td>
    <td>License for the Apache Xalan serializer</td>
   </tr>
   <tr>
    <td>NOTICE.serializer.txt</td>
    <td>NOTICE file for the Apache Xalan serializer</td>
   </tr>
   <tr>
    <td>LICENSE-SAX.html</td>
    <td>SAX License</td>
   </tr>
   <tr>
    <td>LICENSE.DOM-documentation.html</td>
    <td>W3C Document License</td>
   </tr>
   <tr>
    <td>LICENSE.DOM-software.html</td>
    <td>W3C Software License</td>
   </tr>
   <tr>
    <td>build.bat</td>
    <td>Batch file for invoking Ant build for Windows users</td>
   </tr>
   <tr>
    <td>build.sh</td>
    <td>Shell script for invoking Ant build for UNIX users</td>
   </tr>
   <tr>
    <td>build.xml</td>
    <td>Ant build file -- read README file before building</td>
   </tr>
   <tr>
    <td>README</td>
    <td>Build instructions</td>
   </tr>
   <tr>
    <td>Readme.html</td>
    <td>Web page redirect required for building documentation</td>
   </tr>
   <tr>
    <td>data/</td>
    <td>Directory containing sample XML data files</td>
   </tr>
   <tr>
    <td>docs/</td>
    <td>Directory containing documentation, in XML form</td>
   </tr>
   <tr>
    <td>samples/</td>
    <td>Directory containing source code for samples</td>
   </tr>
   <tr>
    <td>src/</td>
    <td>
     Directory containing source code for parser and supplemental APIs
    </td>
   </tr>
  </table>
  <note>
   In order to compile the source code using Ant or to build the
   release distributions yourself, you must have the contents of 
   <code>&ParserName;-tools.&parserversion;.zip</code>
   on your classpath; i.e., you will need access to a version of Ant,
   Xalan, StyleBook and an XML parser such as Xerces.
   For ease of use, we recommend extracting
   <code>&ParserName;-tools.&parserversion;.zip</code>
   in your Xerces root directory; the build.sh and build.bat scripts
   are written for this case.
  </note>
 </s2>
 <s2 title='Changes in Xerces jar files'>
 <p>In order to accommodate the very common case in which Xerces is
 used with an XSLT processor such as Xalan, between Xerces 2.0.0 beta 3
 and beta 4 a change in the default organization of Xerces&apos; jar
 files was introduced.  As well as the <code>xercesSamples.jar</code>
 file, which we still produce, Xerces formerly came with a file called
 <code>xerces.jar</code>.  This file contained all of the
 parser&apos;s functionality.  Two files are now included:
 <code>xercesImpl.jar</code>, our implementation of various APIs,
 and <code>xml-apis.jar</code>, the APIs themselves.  This
 was done so that, if your XSLT processor ships with APIs at the
 same level as those supported by &ParserName;, you can avoid putting
 <code>xml-apis.jar</code> on your classpath.</p>

 <p>Should you wish to use the <code>xerces.jar</code> instead, we have
 included several Ant targets for backward compatibility.  An
 &quot;Ant target&quot; is an argument given to Ant, our build tool,
 that tells it which portions of the <code>build.xml</code> file to
 apply. 
</p>

 <p> 
 If you are on a Windows system and you wish to get only the
 xerces.jar file, you would execute <code>build.bat
 deprecatedjars</code>.  
 </p>
 <p>
 If you want to regenerate new versions of the Xerces
 binary, source and tools distributions with the old-style jar files,
 you would execute <code>build.bat deprecatedall</code>.  

 The situation is
 analogous for Unix users, except that <code>build.sh</code> would be
 used instead of <code>build.bat</code>.  
 </p>
 <p>
 For further information and
 more options, please look inside build.xml itself; all possibilities
 are documented there.
 </p>
</s2>
<s2 title="Verifying signatures">
    <p>In order to provide security-conscious users with the best
    possible assurance that the Xerces distribution they have
    downloaded is official, "signatures" are provided for all 6
    Xerces packages produced in each release.  A signature is
    produced with cryptographic software (such as <jump
    href="http://www.pgp.com">PGP</jump> or <jump
    href="http://www.gnupg.org">GNUPG</jump>).  The cryptographic
    software is used to apply an algorithm that uses the secret
    "key" of a Xerces committer to generate a unique file from
    each Xerces distribution.  The Xerces committer then makes a
    "public" key available, which the user can use, in
    conjunction with the downloaded distribution and the
    accompanying signature, to verify that the distribution was
    actually produced by that committer.
    </p>
    <p>In order to verify the legitimacy of Xerces distributions
    you download, these steps should be followed:</p>
    <ol>
        <li>
            Get a copy of PGP or GNUPG from the above URL's.
        </li>
        <li>
            Obtain the signature of the Xerces package you wish
            to verify.  For instance, if you want to verify the
            legitimacy of Xerces-bin.x.y.z.tar.gz, download the
            Xerces-bin.x.y.z.tar.gz.asc file from the same
            location as the original file was obtained.
        </li>
        <li>
            Obtain a copy of the public key of the Xerces
            committer.  While most committers have posted their
            keys to public "key servers", probably the easiest
            place to get them from is SVN.  The public keys of
            all Xerces committers who post releases are available
            from the file called <code>KEYS</code> located in the
            root directory of the <code>http://svn.apache.org/repos/asf/xerces/java/trunk/</code>
            repository.
        </li>
        <li>
            Add these keys to your "public" keyring.  In GNUPG,
            you'd do this with a command like <code>gpg --import
            KEYS</code>.
        </li>
        <li>
            Issue the command for verifying signatures
            appropriate for the cryptographic software you've
            chosen.  For GNUPG, this would be 
            <code>gpg --verify Xerces-J-foo.x.y.z.ext.asc
            Xerces-J-foo.x.y.z.ext</code>.
        </li>
    </ol>
    <p>Note that, in general, it won't be necessary to acquire new copies
    of public keys to verify signatures for each Xerces release.
    This will only be necessary if a new Xerces committer has
    published the release.  
    </p>
</s2>
</s1>