You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by dl...@locus.apache.org on 2000/09/19 14:52:41 UTC

cvs commit: xml-xalan/java/xdocs/sources/xalan STATUS extensions.xml readme.xml samples.xml usagepatterns.xml whatsnew.xml

dleslie     00/09/19 05:52:41

  Modified:    java/xdocs/sources/xalan STATUS extensions.xml readme.xml
                        samples.xml usagepatterns.xml whatsnew.xml
  Log:
  Editorial updates
  
  Revision  Changes    Path
  1.2       +4 -0      xml-xalan/java/xdocs/sources/xalan/STATUS
  
  Index: STATUS
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/STATUS,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- STATUS	2000/09/15 19:03:20	1.1
  +++ STATUS	2000/09/19 12:52:36	1.2
  @@ -4,6 +4,10 @@
   <note>You can use Xalan with other conformnant SAX and DOM parsers. </note>
   </s3><anchor name="to-do"/>
   <s3 title="To-do tasks">
  +  <ul>
  +    <li>Complete implementation of &xslt4j2;</li>
  +    <li>Add extensions to extensions library</li>
  +</ul>
        <p>As part of the xml.apache team, members of the &xslt4j; team are also exploring options to upgrade the integration of all
        the xml.apache projects, including Xalan, Xerces, Cocoon, and FOP.</p>
       <p>The more individuals who join in the design, development, testing, documentation, and use of
  
  
  
  1.2       +1 -1      xml-xalan/java/xdocs/sources/xalan/extensions.xml
  
  Index: extensions.xml
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/extensions.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- extensions.xml	2000/09/15 19:03:20	1.1
  +++ extensions.xml	2000/09/19 12:52:37	1.2
  @@ -296,7 +296,7 @@
       Testing Redirect extension:
       &lt;foobar-out&gt;foo subelement text node&lt;/foobar-out&gt;
     &lt;/foo-out&gt;</source>
  -<p>For more information on using the Redirect extension to send output to multiple files, see <resource-ref idref="RedirectDoc"/>.</p>  
  +<p>For more information on using the Redirect extension to send output to multiple files, examine the <link idref="samples" anchor="ext1">SimpleRedirect</link> sample and see the <jump href="apidocs/org/apache/xalan/lib/Redirect.html">Redirect</jump>class Javadoc.</p>  
   </s3>
   </s2><anchor name="ext-functions"/>
   <s2 title="Using extension functions">
  
  
  
  1.2       +50 -10    xml-xalan/java/xdocs/sources/xalan/readme.xml
  
  Index: readme.xml
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/readme.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- readme.xml	2000/09/15 19:03:20	1.1
  +++ readme.xml	2000/09/19 12:52:37	1.2
  @@ -70,10 +70,13 @@
    </ul>
     <s2 title="Status">
      <ul>
  +    <li><link anchor="done">Changes since version 1.2.D01</link></li>    
       <li><link anchor="bugs">Open bugs and bug reporting</link></li>
       <li><link anchor="status">Version of Xerces to use</link></li>
       <li><link anchor="to-do">To-do tasks for future &xslt4j; releases</link></li>
      </ul>
  +     <anchor name="done"/>
  +     &done-j;     
        <anchor name="bugs"/>
        &bugs-j;
        <anchor name="status"/>
  @@ -91,10 +94,11 @@
   <anchor name="ant"/>
      <s3 title="Using Ant">
        <p>Apache <resource-ref idref="ant"/> is a flexible, powerful, and easy-to-use Java build tool that we include with the
  -     &xslt4j; distribution. The Ant JAR file is in the bin directory along with a cross-platform XML build file (build.xml), a
  +     &xslt4j; distribution. The Ant JAR file is in the root directory along with a cross-platform XML build file (build.xml), a
        Windows32 batch file (build.bat) and a UNIX shell file (build.sh). The build file defines the "targets" that you can use Ant
        to build. The batch and shell files set up the classpath and launch Ant with the target (and any other arguments) you
        provide.</p>
  +     <note>We still use makefiles to build the distribution copy of &xslt4j;.</note>
        <p><em>Instructions for using Ant</em></p>
        <ol>
          <li>Set the JAVA_HOME environment variable to the JDK root directory.<br/><br/>
  @@ -114,8 +118,7 @@
          <tr><td><em>Target</em></td><td><em>What Ant does</em></td></tr>
          <tr><td>compile</td><td>compiles Xalan-J in build/classes.</td></tr>
          <tr><td>jar</td><td>creates xalan.jar in the build directory (the default)</td></tr>
  -       <tr><td>samples</td><td>compiles and jars the sample apps (except the sample servlet)</td></tr>
  -       <tr><td>servlet</td><td>compiles and jars the sample servlet</td></tr>       
  +       <tr><td>samples</td><td>compiles and jars the sample apps</td></tr>
          <tr><td>docs</td><td>creates the HTML User's Guide in build/docs</td></tr>
          <tr><td>javadocs</td><td>generates the API documentation in ./build/docs/apidocs</td></tr>
          <tr><td>dist</td><td>creates a complete distribution in xalan-j_<ref>x</ref>_<ref>y</ref>_<ref>z</ref></td></tr>
  @@ -124,14 +127,31 @@
          in the source tree for doc and Javadoc builds</td></tr> 
     </table>
     <p>If you build a target that depends on other targets, Ant creates those other targets in the correct order.</p>
  -  
  +  <p><em>Other build tools</em></p>
  +  <p>The distribution also includes makefiles that you can use with the GNU development tools. And of course you can also use 
  +  the underlying utilities to compile source files, create JAR files, generate Javadoc, and generate the HTML User's Guide. One
  +  utility that you may not be familiar with is org.apache.stylebook.StyleBook (in stylebook-1.0-b2.jar), a tool from the
  +  xml-stylebook module that we use along with Xalan and Xerces to help generate the documentation. For the details, you can
  +  inspect the makefiles.</p>
        
      </s3><anchor name="jar"/> 
      <s3 title="Rebuilding &xslt4j;">
        <p>The &xslt4j; build is in xalan.jar. The &xslt4j; source code tree is in the src directory.</p>
        <p>If you are using Ant, the target is jar (the default). For more information, see <link anchor="ant">Using
        Ant</link>.</p>
  -     <p>If you want to do the build without Ant, keep the following in mind:</p>
  +     <p>To use GNU development tools, do the following:</p>
  +     <ol>     
  +       <li>Set up GNU or the equivalent build environment on your workstation.<br/><br/>
  +       If you are running Windows 95/98/2000/NT, you can use the Cygwin port of GNU. Be sure to put the
  +       appropriate Cygwin bin directory at the beginning of your system path. For information about
  +       Cygwin, see <jump href="http://www.sourceware.cygnus.com/cygwin/">Cygwin</jump>.<br/><br/></li>
  +       <li>Place <resource-ref idref="xml4j-used"/> xerces.jar in the Java class path.<br/><br/></li>
  +       <li>If you are working in Windows, set MAKE_MODE as follows:<br/><br/>
  +       <code>set MAKE_MODE=UNIX</code><br/><br/></li>
  +       <li>Run the make file in the &xslt4j; root directory:<br/><br/>
  +       <code>make build</code><br/><br/></li>
  +     </ol>
  +     <p>If you want to do the build without Ant or the GNU build environment, keep the following in mind:</p>
        <ul>
        <li>Set the class path to include the src directory, xerces.jar, bsf.jar, and bsfengines.jar.</li>
        <li>Use a Java compiler (such as the IBM Just-In-Time compiler or the Sun javac) to compile all the .java files in the src
  @@ -156,15 +176,31 @@
         files, entity relationship (ENT) files, graphics, and a JavaScript file that provide the input for the Xalan
         HTML User's Guide, and the overview and package-level documents used during the generation of Javadoc.</p>
         <p>To rebuild the documentation, you must use the StyleBook tool and the JDK 1.2.2 java and javadoc
  -      tools. StyleBook (which uses Xalan and Xerces) is in stylebook-1.0-b3_xalan-2.jar. Some of the document definition files,
  -      stylesheets, and resources are stored in xml-site-style.tar.gz, and are unzipped when you run the Ant build.</p>
  +      tools. StyleBook (which uses Xalan and Xerces) is in stylebook-1.0-b2.jar. Some of the document definition files,
  +      stylesheets, and resources are stored in xml-site-style.tar.gz, and are unzipped when you run the make files as described
  +       below. If the JDK 1.2.2 bin and lib directories are not on your class path, you can edit the make.include file in the
  +       Xalan root directory so the make file can find the JDK 1.2.2 java and javadoc tools. You can also include java and javadoc
  +       arguments on the make file command line. See the make.include file for the details.</p>
         <p>You can use Ant with the docs target to regenerate the User's Guide and with the javadocs target to regenerate the
         Javadoc API documentation. For more information, see <link anchor="ant">Using Ant</link>.</p>
  -       <p>If you want to rebuild the documentation without using Ant, keep the following in mind:</p>
  +     <p>To generate the Xalan HTML User's Guide with the GNU development tools, run the Xalan make file in the Xalan xdocs
  +     directory:<br/><br/>
  +     <code>make makesbook</code></p>
  +     <p>To generate the Xalan API documentation with GNU, set up the make file to use the Javadoc tool in the Java JDK 1.2.2 bin 
  +     directory.</p>
  +     <p>Do the following:</p>
  +       <ol>
  +         <li>Put the Java JDK 1.2.2 bin directory on your path (in front of any JDK 1.1.x bin 
  +         directory that appears on the path).<br/><br/></li>
  +         <li>In the Xalan docs directory, run the Xalan make file as follows:<br/><br/>
  +         <code>make makejavadoc</code><br/><br/></li>
  +      </ol>
  +      <p>If you want to rebuild the documentation without using Ant or the GNU build environment, keep the following in
  +       mind:</p>
          <ul>
          <li>Unzip xml-site-style.tar.gz into the xdocs directory (the operation places files in a number of subdirectories).
          <br/><br/></li>
  -       <li>Be sure stylebook-1.0-b3_xalan-2.jar, xalanjdoc.jar, xalan.jar, bsf.jar, bsfengines.jar, and xerces.jar are on the class
  +       <li>Be sure stylebook-1.0-b2.jar, xalanjdoc.jar, xalan.jar, bsf.jar, bsfengines.jar, and xerces.jar are on the class
          path.<br/><br/></li>
          <li>To build doc in a build/docs subdirectory, run StyleBook from the xdocs directory as follows:<br/><br/>
          <code>java org.apache.stylebook.StyleBook "targetDirectory=../build/docs/" sources/xalanLocal.xml style</code>
  @@ -175,7 +211,7 @@
           <li>Before you run javadoc, make sure the following directory structure exists under the Xalan root
            directory: build/docs/apidocs.<br/><br/></li>
          <li>To build the API documentation, run the JDK 1.2.2 javadoc tool from the xdocs directory:<br/><br/>
  -<code>-doclet xalanjdoc.Standard -public -overview ../src/javadocOverview.html -sourcepath ../src -group XSLT_Packages "org.apache.xalan.xslt*" -group XPath_Packages "org.apache.xalan.xpath*" org.apache.xalan.xpath org.apache.xalan.xpath.xdom org.apache.xalan.xpath.dtm org.apache.xalan.xpath.xml org.apache.xalan.xslt org.apache.xalan.xslt.trace org.apache.xalan.xslt.client org.apache.xalan.xslt.extensions -windowtitle Xalan -d ../build/docs/apidocs
  +<code>javadoc -doclet xalanjdoc.Standard -docletpath ../bin/xalanjdoc.jar -private -overview ../src/javadocOverview.html -sourcepath ../src -group TrAX "trax" -group Xalan_Core "org.apache.xalan.processor:org.apache.xalan.templates:org.apache.xalan.transformer" -group XPath "org.apache.xpath*:org.w3c.xslt" -group Xalan_Other "org.apache.xalan.client:org.apache.xalan.dtm:org.apache.xalan.extensions:org.apache.xalan.res:org.apache.xalan.stree:org.apache.xalan.trace:org.apache.xalan.utils" -group Xalan_Extensions "org.apache.xalan.lib*" -group Serializers "serialize*" -group Xalan-Java_1_Interface "org.apache.xalan.xslt:org.apache.xalan.xpath" org.apache.xalan.client org.apache.xalan.dtm org.apache.xalan.extensions org.apache.xalan.lib org.apache.xalan.lib.sql org.apache.xalan.processor org.apache.xalan.res org.apache.xalan.stree org.apache.xalan.templates org.apache.xalan.trace org.apache.xalan.transformer org.apache.xalan.utils org.apache.xalan.xpath org.apache.xalan.xpath.xml org.apache.xalan.xslt org.apa
che.xpath org.apache.xpath.axes org.apache.xpath.compiler org.apache.xpath.functions org.apache.xpath.objects org.apache.xpath.operations org.apache.xpath.patterns org.apache.xpath.res org.w3c.xslt serialize serialize.helpers trax -d ../build/docs/apidocs -windowtitle "Xalan-Java 2" -doctitle "Xalan-Java 2" -bottom "Copyright &#169; 2000 Apache XML Project. All Rights Reserved."
   </code></li>
   </ul>
     </s3>    
  @@ -183,5 +219,9 @@
    <s2 title="Getting in Touch">
     <p>Your feedback is more than welcome. Offers of help are even more so! Perhaps you would like to take on an active role in the ongoing development, testing, and documentation of &xslt4j;?</p> 
   <p>Please email your comments, questions, suggestions, and offers to join the Xalan team to <human-resource-ref idref="xalandev"/>.</p>
  + </s2><anchor name="history"/>
  + <s2 title="Cumulative history of software changes">
  +   <note>We started tracking the changes in earlier releases beginning with &xslt4j; version 1.1.</note>
  +
    </s2>
   </s1>
  
  
  
  1.4       +10 -6     xml-xalan/java/xdocs/sources/xalan/samples.xml
  
  Index: samples.xml
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/samples.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- samples.xml	2000/09/15 19:02:28	1.3
  +++ samples.xml	2000/09/19 12:52:37	1.4
  @@ -72,7 +72,7 @@
        sample applications. The class files for the samples are in xalansamples.jar (everything except the servlet) and xalanservlet.jar, so to run the samples, you should place these JAR files on the system classpath.</p>
        <p>With most of the samples, you can use the following procedure:</p>
        <ol>
  -     <li>Be sure xalan.jar, xalansamples.jar (xalanservlet.jar for the servlet), and xerces.jar are on the system class
  +     <li>Be sure xalan.jar, xalansamples.jar, and xerces.jar are on the system class
         path. For the extension examples, bsf.jar, bsfengines.jar, and (for the JavaScript extensions) js.jar must also be on the class
         path.</li>
        <li>Be sure the java executable is on your path.</li>
  @@ -85,9 +85,10 @@
       <p>The basic command line for running most of the samples is </p> 
       <p><code>java <ref>classname args</ref></code></p>
       <p>where <ref>classname</ref> is the classname and <ref>args</ref> are the arguments, if any. As described in
  -     the following sections, some samples take no arguments. The samples in UseStylesheetParam and xxx take
  -     additional arguments. The samples in extensions use the &xslt4j; <link idref="commandline">command-line
  -     utility</link>, so they take arguments for the XML source file and the XSL stylesheet.</p>
  +     the following sections, some samples take no arguments. The UseStylesheetParam sample takes an
  +     additional argument. Several samples in extensions use the &xslt4j; 
  +     <link idref="commandline">command-line utility</link>, so they take arguments for the XML source
  +     file and the XSL stylesheet.</p>
     	</s2><anchor name="simpletransform"/>
       <s2 title="SimpleTransform">
       <p>What it does: The SimpleTransform class uses the foo.xsl stylesheet to transform foo.xml, and prints the
  @@ -112,7 +113,7 @@
       </s2><anchor name="sax2sax"/>
     <s2 title="SAX2SAX">
     <p>What it does: Explicitly set the SAX XMLReader and SAX ContentHandler for processing the stylesheet, processing the XML input, and producing the output.</p>
  -  <p>Run this sample from the Pipe subdirectory with</p>
  +  <p>Run this sample from the Sax2sax subdirectory with</p>
      <p><code>java SAX2SAX</code></p>
       </s2><anchor name="pipe"/>
       <s2 title="Pipe">
  @@ -162,6 +163,9 @@
   </gloss>
        </s2><anchor name="extensions"/>
       <s2 title="Extensions">
  +    <p>For an introduction to the creation and use of extension elements and extension functions, and
  +    for information about the extensions library distributed with &xslt4j;, see
  +    <link idref="extensions">Extensions</link>.</p>
       <ul>
         <li><link anchor="ext1">SimpleRedirect</link></li>
         <li><link anchor="ext2">2-basicJscript</link></li>
  @@ -172,7 +176,7 @@
       <p>The extensions subdirectory contains five samples with &xslt4j; extensions. Two of the samples use
        extensions implemented in JavaScript, and three of the samples use extensions implemented in Java.</p>
        <p>To run these examples, you must place bsf.jar and bsfengines.jar (distributed with &xslt4j;), and js.jar
  -      (version 1.4 release 3, available from 
  +      (version 1.5, available from 
         <jump href="http://www.mozilla.org/rhino">http://www.mozilla.org/rhino</jump>) on the class path. 
        You do not need js.jar on the class path for the samples that use Java extensions. </p>
        <p>Use java.org.apache.xalan.xslt.Process, the &xslt4j; command-line utility, to run most of these samples from
  
  
  
  1.2       +5 -4      xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml
  
  Index: usagepatterns.xml
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/usagepatterns.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- usagepatterns.xml	2000/09/15 19:03:20	1.1
  +++ usagepatterns.xml	2000/09/19 12:52:37	1.2
  @@ -1,4 +1,4 @@
  -<?xml version="1.0" standalone="no"?> 
  +-<?xml version="1.0" standalone="no"?> 
   <!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
   <!--
    * The Apache Software License, Version 1.1
  @@ -118,6 +118,7 @@
   <s2 title="4. Perform a transformation">
   <p>Supply the XML input, a target or "holder" for the transformation output, and instruct the Transformer to perform the transformation.</p>
   <p>Just as with the stylesheet, you can supply the XML input in the form of a SAX input source (from a URL or stream) or a DOM tree.</p>
  +<p>Use the Transformer transform() method with a SAX input source (as in the example above), or the transformNode() method with a DOM tree to perform the transformation.</p>
   <p>TRaX provides the holder for the output: trax.Result. You can set up a Result object to send the transformation result to a file or stream or to build a DOM tree.</p>
   <p>The Transformer uses the SAX XMLParser to parse the XML input and sends parse events to an input SAX ContentHandler, org.apache.xalan.stree.SourceTreeHandler, which in turn uses org.apache.xalan.utils.DOMBuilder to assemble the input into a DOM tree. Of course this operation is unnecessary if the XML input is submitted as a DOM.</p>
   <p>For each node in the XML source, the Transformer uses the Templates object and underlying XSLT schema to determine which template to apply: one of the templates in the Templates object, a default template rule as specified in the XSLT spec, or none.</p>
  @@ -130,13 +131,13 @@
   <p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 boo</code></p>
   <p>or</p>
   <p><code>java org.apache.xalan.xslt.Process -in foo.xml -xsl foo.xsl -param param1 org/myorg/xyz boo</code></p>
  -<p>where <code>org/myorg/xyz</code> is the parameter namespace. [not yet working]</p>
  +<p>where <code>param</code> is the parameter name, <code>org/myorg/xyz</code> is the parameter namespace. [not yet working], and <code>boo</code> is the parameter value. Unless you have defined a namespace for the parameter, the parameter namespace is null.</p>
   </s2><anchor name="sax"/>
   <s2 title="Explicitly working with SAX">
     <p>&xslt4j; uses the SAX event model to process stylesheets, to parse XML input documents, and to produce output. For each of these operations, an XMLReader reads input, firing parse events, and a ContentHandler listens to the XMLReader and performs parse event methods.</p>
  -<p>When you use the basic procedure described above for performing transformations, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate the specific conditions in which your application operates.</p>
  +<p>When you use the basic procedure described above for performing transformations, &xslt4j; takes care of many of the SAX details under the covers. You are free to make these details explicit, which simply means that you can intervene in the procedure to accommodate any custom conditions in which your application operates.</p>
   <p>Suppose, for example, you are using a custom XMLReader (perhaps doing more than just parsing static XML documents) to generate &xslt4j; SAX parse events. You can instruct the Transformer to provide the ContentHandler for this XMLReader. You might even have a custom reader for producing/processing stylesheets, in which case you simply set the trax.TemplatesBuilder (implemented by the org.apache.xalan.processor.StylesheetHandler) as the ContentHandler for this reader.</p>
  -  <p>The following example replicates the <link anchor="basic">Basic 4 steps</link> described above</p>
  +  <p>The following example explicitly sets up the XMLReader and ContentHandlers, and replicates the <link anchor="basic">basic steps</link> described above.</p>
     <source>// 1. Instantiate  stylesheet processor.
   trax.Processor processor = trax.Processor.newInstance("xslt");
   
  
  
  
  1.7       +1 -1      xml-xalan/java/xdocs/sources/xalan/whatsnew.xml
  
  Index: whatsnew.xml
  ===================================================================
  RCS file: /home/cvs/xml-xalan/java/xdocs/sources/xalan/whatsnew.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- whatsnew.xml	2000/09/15 19:02:28	1.6
  +++ whatsnew.xml	2000/09/19 12:52:37	1.7
  @@ -70,7 +70,7 @@
       <p>In conjunction with TRaX, &xslt4j; gathers basic operational settings from system properties. System properties, for example, identify the stylesheet processor and SAX parser to use, and the serializers that are available for various output methods. The default settings point to the Xalan StylesheetProcessor, the Xerces SAXParser, and the serializers shipped with Xerces.</p>
   </s2><anchor name="packages"/>
     <s2 title="Package layout">
  -  <p>As the new package structure (outline below) highlights, the processing of stylesheets and production of stylesheet templates, the application of stylesheet templates to source trees and production of output trees, the evaluation of XPath expressions and XSLT matching patterns, and subsidiary operations and utilities are more clearly segmented than in &xslt4j; version 1.</p> 
  +  <p>As the new package structure highlights, the processing of stylesheets and production of stylesheet templates, the application of stylesheet templates to source trees and production of output trees, the evaluation of XPath expressions and XSLT matching patterns, and subsidiary operations and utilities are more clearly segmented than in &xslt4j; version 1.</p> 
   <p>&xslt4j2; is made up of four major and several minor modules. The four major modules are:</p>
   <gloss> 
   		<label><jump href="apidocs/org/apache/xalan/processor/package-summary.html">org.apache.xalan.processor</jump></label>