xalan-dev list proto-FAQ v0.2 - Readme First!

[Sh...@lotus.com]

A quick take on a few of the FAQs I've seen lately on the list. New/Updated
items from the immediately-preceding proto-FAQ marked with leading *.

We have eventual plans for a more formal FAQ (all in XML, of course, and
automatically posted to the website in a searchable manner, and mailed to
the list periodically magically including an attachment of cookies and milk
for all...  8-) but in the meantime, here's a few quick answers.  Apologies
in advance for making all the code examples in Java; perhaps someone else
has some C++ FAQs?

---- Contents: questions ----------------
Q: How do I search xalan-dev posts?
Q: How do I write/fix/update my XSLT stylesheet to ...
Q: I'm getting NoSuchMethod error with Xalan and Tomcat...
*Q: I'm getting an unusual error relating to DOM classes, SAX classes,
javax.xml.* classes - what's wrong?
Q-: I'm getting a "Namespace not supported by SAXParser" exception - what's
wrong?
Q-: I'm getting a an error about my stylesheet missing the xsl:version
attribute - what's wrong?
*Q-: My DOMSource can't be built/transformed - what's wrong?
Q: How come my xsl:include/import file isn't found?
Q: Why do I get 'file not found' when I pass c:\path\filename.txt?
*Q: My transform/process seems to complete but there's nothing in the
output file!
Q: How do I unsubscribe from this list? Help!
*Q: How do I submit a bug about Xalan?
Q: How do I submit a patch to Xalan?
*Q: Is this FAQ useful to you?

---- Contents: answers ----------------
Q: How do I search xalan-dev posts?
A: http://marc.theaimsgroup.com/?l=xalan-dev&r=1&w=2  (Many thanks to the
AIMS Group for hosting!)


Q: How do I write/fix/update my XSLT stylesheet to create XHTML / make
tables / do something special...
A: Stop right there.  This is the xalan-dev list, for discussions about how
Xalan itself works and is developed, not a general tutorial on writing XSLT
stylesheets.  We try to help when we can but you'll get better and quicker
help in other places.  Join the famed xsl-list at Mulberrytech, or see one
of the references/tutorials/guidebooks below:

  http://xml.apache.org/xalan-j/overview.html#uptospeed
  http://mulberrytech.com/xsl/xsl-list/index.html
  http://www.dpawson.co.uk/xsl/xslfaq.html
  http://www.objectsbydesign.com/projects/xslt/xslt_by_example.html
  http://www.zvon.org/xxl/XSLTutorial/Books/Book1/index.html


Q:<df...@coremetrics.com>
I am getting an error message that I think is due to a class conflict
between XALAN & TOMCAT. Running the xalan servlet example generates an
error:
java.lang.NoSuchMethodError
 at org.apache.xpath.DOM2Helper.getLocalNameOfNode(DOM2Helper.java:326)
 ...
A: <ly...@ssmb.com>
If using Tomcat < 4.0 then put the Xalan classes in the tomcat.[bat|sh]
CLASSPATH definition BEFORE xml.jar

*Q: I'm getting an unusual error relating to DOM classes, SAX classes,
javax.xml.* classes - what's wrong?
NOTE: A number of seemingly odd NoSuchMethod or other exceptions can be due
to classpath ordering issues.  Many products include their own copies of
the org.w3c.dom.*, org.xml.sax.*, and javax.xml.* standard packages, some
of which may be outdated or incompatible.  Xalan relies on finding the
versions of these packages either in xalan.jar or xerces.jar, so a number
of problems can be solved by either putting xalan.jar/xerces.jar earlier or
first on the CLASSPATH, and by searching your classpath or extensions
directory for other jars that might include these standard packages -
especially versions of jaxp.jar, parser.jar, xml.jar, crimson.jar.

* NOTE-ALSO: If using any JDK 1.2+ or higher, you must also check your
/lib/ext or extensions directory for copies of the above files, since they
are 'magically' included in the beginning of your classpath.  To get rid of
files in your extensions directory, you must delete them or move them out
of the directory - simply renaming them will *not* work (maybe: rename the
extension to not be .jar, but I haven't tested this).


Q-: I'm getting a "Namespace not supported by SAXParser" exception - what's
wrong?
Q-: I'm getting a an error about my stylesheet missing the xsl:version
attribute - what's wrong?
*Q-: My DOMSource can't be built/transformed - what's wrong?
A: Make sure you have a namespace-aware parser configured.  Some parsers
support namespaces by default, some you have to ask for support.  Try
adding something like the second line here:
  javax.xml.parsers.SAXParserFactory factory =
javax.xml.parsers.SAXParserFactory.newInstance();
  factory.setNamespaceAware(true); // Xerces needs this set


Q: How come my xsl:include/import file isn't found?
A: Did you remember to setSystemId() on your Source objects? When passing
any kind of InputStream, Reader, or Node object to Xalan as the source for
your stylesheet, you should also set the systemId on the object so Xalan
knows where to resolve URL's from.  A short example with Xalan-J 2.x:

  // When using InputStream/Reader/Node, must also setSystemId()
  java.io.InputStream xslStream = new FileInputStream
("/local/path/to/file.xsl");
  jaxax.xml.transform.Source xslSource = new
jaxax.xml.transform.stream.StreamSource(xslStream);
  xslSource.setSystemId("file:///legal/url/to/file.xsl");

  // Using a URL string effectively sets systemId for you
  jaxax.xml.transform.Source xmlSource = new
jaxax.xml.transform.stream.StreamSource(xmlURL);

  jaxax.xml.transform.Templates templates =
factory.newTemplates(xslSource);
  jaxax.xml.transform.Transformer transformer = templates.newTransformer();
  transformer.transform(xmlSource, result);


Q: Why do I get 'file not found' when I pass c:\path\filename.txt?
A: Xalan often requires legal URLs as system identifiers, not local
pathnames (this is partly due to underlying parsers requiring this).  A
simple (but not always correct!) way to change a local pathname into a URL
in Java 1.1x is:
  public static String filenameToURL(String filename)
  {
    File f = new File(filename);
    String tmp = f.getAbsolutePath();
    if (File.separatorChar == '\\')
    {
      tmp = tmp.replace('\\', '/');
    }
    // Note: gives incorrect results when filename already begins with
file:///
    return "file:///" + tmp;
  }
For a slightly more detailed example, see org.apache.xml.utils.
SystemIDResolver

Learn more about the details of URL/URIs:
  ftp://ftp.isi.edu/in-notes/rfc1738.txt
  ftp://ftp.isi.edu/in-notes/rfc1808.txt
  ftp://ftp.isi.edu/in-notes/rfc2396.txt


*Q: My transform/process seems to complete but there's nothing in the
output file!
*A: Did you flush/close your outputStream?  Remember, if you create a
stream, you are responsible for flushing it.  Compare and contrast the
following two examples:

  // Create a result from a String / URI: Xalan owns the underlying
'stream'
  transformer.transform(xmlSource, new StreamResult
("file:///c:/bar/foo.xml"));

  // Create a result from a Writer / OutputStream: you own the underlying
stream
  FileOutputStream fos = new FileOutputStream("c:\bar\foo.xml");
  transformer.transform(xmlSource, new StreamResult(fos));
  fos.flush() // needed to ensure output written out!


Q: How do I report a bug about Xalan?
* A: Make your subject line start with [BUG] and then briefly describe
what's
not working in the subject line.  Please do *not* simply put "[Xalan-J 2
bug]" in your subject line alone, as it's very hard to tell which one is
which (I'm reading three! on the same day right now).
Then in the body of the email, describe clearly and completely what your
code is trying to do, what actually happened (presumably the bug), and what
you expected to happen (the desired behavior).

Be *sure* to specify those other important details - like which Xalan build
(Java/C++) and specific verison number you're using, which platform and
JDK/compiler; etc.  And be sure to include at least a snippet of the code
you executed along with any stacktraces or error printouts.  If the code
isn't simple, then please attach enough code (plus stylesheets and XML
documents) to reproduce the basic problem.  .Zip or .tar.gz files are fine
to save space.  One of the more common requests on the list is asking bug
reporters to send in their stylesheets - we can't work on it if we can't
reproduce the problem ourselves.


Q: How do I submit a patch to Xalan?
A: Make your subject line start with [PATCH] and then note the filename(s)
and briefly what the patch does.
In the body of the email, describe what you patched and why, and any
questions or hints you might have for committers who will be reviewing the
patch.  Always include the patch as an attachment to the email: this
prevents problems with mailers that wrap long lines.  If the patch is
small, then *also* include a copy of the patch in the body of the email
itself (which makes it quicker to review).
The best way to create a patch currently (someone suggest better ways as
needed) is to use the CVS diff command like so:
  cvs diff -u FileName.java >> FileName.java.patch
This creates a _u_nified diff of your local FileName.java against the most
recent revision in the repository, putting the output into
FileName.java.patch
For hints on using CVS, see http://xml.apache.org/cvs.html


Q: How do I unsubscribe from this list? Help!
A: Don't panic!  And please don't send unsubscribe reqests to the list.
See:
http://xml.apache.org/mail.html


Oh, and the question that should be obvious:
Q: Where's the Xalan homepages?
A: http://xml.apache.org/xalan-j/
   http://xml.apache.org/xalan-c/


*Q: Is this FAQ useful to you?
A: Well, is it?  Comments please!  Specific comments, especially from
volunteers to help out with either the list, this FAQ, or our website are
even better...


- Shane