xdocs/sources/xalan/faq.xml - xalan-c - Git at Google

 <?xml version="1.0" standalone="no"?>
 <!DOCTYPE faqs SYSTEM "../../style/dtd/faqs.dtd">

 <faqs title="Frequently asked questions">

   <faq title="Where do I go to learn about XSLT">
     <q>Where do I go to learn about XSLT?</q>

     <a><p>The definitive sources are the W3C XSLT and XPath recommendations: <resource-ref idref="XSLT"/> and
     <resource-ref idref="XPath"/>.</p>
     <p>For general questions not specific to &xslt4c;, see Dave Pawson's <resource-ref idref="dpawsonxslfaq"/> and Michael Kay's
     <jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's Reference</jump>.</p>
     <p>For a brief listing of tutorials, discussion forums, and other materials, see <link idref="overview"
      anchor="uptospeed">Getting up to speed with XSLT</link>.</p></a>
   </faq>

 <faq title="Questions"><q>Where can I ask question?</q>

 <a><p>For generic questions about XSL stylesheets and transformations, use the <jump href="http://www.mulberrytech.com/xsl/xsl-list/">XSL-List -- Open Forum on XSL</jump> hosted by Mulberry Technologies. There is an archive that can be searched as well. Specific questions about &xslt4c; can be asked on the Xalan-dev list. Please review this document and the archives before posting new questions.</p>

 <p>For specific questions on &xslt4c;, see xalan-dev@xml.apache.org on <jump href="http://archive.covalent.net/">http://archive.covalent.net/</jump>.</p>
 </a>
 </faq>

 <faq title="What is &xml4c;?">
 <q>What is &xml4c; and why do I need it?</q>

 <a><p>&xml4c; is a validating XML parser written in a portable subset of C++. &xml4c; makes it easy to give your application the ability to read and write XML data. Like &xslt4c;, &xml4c; is available from the Apache XML site:  http://xml.apache.org/xerces-c/index.html</p><!--xml4cNote--></a>
 </faq>


   <faq title="Which version of Xerces should I be using?">
     <q>Which version of Xerces should I be using?</q>

     <a><p>The &xslt4c; release notes includes information about the &xml4c; release with which the &xslt4c; release has been coordinated and tested. See <link idref="readme" anchor="status">Status</link></p><!--xml4cNote--></a>
   </faq>

 <faq title="Problems with samples in Windows">
 <q>I have encountered problem executing the &xslt4c; sample applications after rebuilding them under Win32 Environment (Windows NT 4.0, SP3).
  When I tried to execute the sample, I receive the error message "Debug Assertion Failed! ...  Expression: _BLOCK_TYPE_IS_VALID(pHead->nBlockUse)".</q>

 <a><p>You may be mixing debug and release versions of executables and libraries. In other words, if you are compiling the sample for debug, then you should link with the debug version of the &xslt4c; and &xml4c; libraries and run with the debug version of the dynamic link libraries.</p><anchor name="build"/><p/></a>
 </faq>

 <faq title="Building on Windows">
 <q>What do I need to rebuild &xslt4c; on Windows?</q>

 <a><p>To build &xslt4c; on Windows, you need &xml4c; and MS Visual C++ 6.0 installed with Service Pack 3 for Visual C++ and Visual Studio. You should also apply the bug fixes for the C++ standard library that shipped with Visual C++ 6.0. These fixes are available from the Dinkumware site: <jump href="http://www.dinkumware.com/vc_fixes.html">http://www.dinkumware.com/vc_fixes.html</jump>.</p>
 <p>For more details, see <link idref="readme" anchor="win32">Steps for doing a Windows build</link>.</p></a>
 </faq>

 <faq title="Building on UNIX">
 <q>What do I need to rebuild &xslt4c; on UNIX?</q>

 <a><p>To build &xslt4c; on supported UNIX platforms, you need &xml4c; and a supported C++ compilers (see the table below). If your compiler does not support the STL or its implementation is old, you must install the STLPort.</p>
 <p>For more details see: http://xml.apache.org/xalan-c/readme.html#unix</p>
      <table>
        <tr>
          <th>Platform - Operating System</th>
          <th>Compilers</th>
          <th>STLPort Required</th>
        </tr>
        <tr>
          <td>AIX 4.3</td>
          <td>IBM C and C++ for AIX 5.02</td>
          <td>No</td>
       </tr>
        <tr>
          <td>Solaris 2.6</td>
          <td>[Workshop 4.2]</td>
          <td>Yes</td>
       </tr>
        <tr>
          <td>HP/UX 11.0</td>
          <td>aCC A.03.27</td>
          <td>No</td>
       </tr>
        <tr>
          <td>Red Hat Linux 6.1</td>
          <td>egcs-2.91.66 and glibc-2.1.2-11</td>
          <td>No</td>
       </tr>
     </table>
  <p>For more details see: <link idref="readme" anchor="unix">Steps for doing a UNIX build</link>.</p>
 </a></faq>

 <faq title="STLPort">
 <q>What is STLPort and why do I need it?</q>

 <a><p>The Standard Template Library, or STL, is a C++ library of container classes, algorithms, and iterators; it provides many of the basic computer science algorithms and data structures. &xslt4c; implementation uses the STL. STLport ports SGI STL to any platform possible and provides all necessary wrap-ups installed. If your compiler does not support the STL or its implementation is out of date, you will need to install the STLPort.</p>

 <p>The STLPort version 4.0  for download from the site: <jump href="http://www.stlport.org/">http://www.stlport.org/</jump>.</p>

 <p>For more details on the STL, see: <jump href="http://www.sgi.com/tech/stl/stl_introduction.html">http://www.sgi.com/tech/stl/stl_introduction.html</jump>.</p></a>
 </faq>

 <faq title="ICU">
 <q>What is ICU and why do I need it?</q>

 <a><p>The International Components for Unicode(ICU) is a C and C++ library that provides robust and full-featured Unicode support on a wide variety of platforms. &xslt4c; uses the ICU to extend support for encoding, number formatting, and sorting.</p>
 <p>The ICU is available for download from <jump href="http://oss.software.ibm.com/developerworks/opensource/icu/project/index.html">http://oss.software.ibm.com/developerworks/opensource/icu/project/index.html</jump>.</p>
 <p>For more details see: <link idref="usagepatterns" anchor="icu">Using the International Components for Unicode (ICU)</link>.</p><!--icuNote--><anchor name="gnutar"/><p/></a>
 </faq>

    <faq title="A tar checksum error on Solaris">
       <q>I am getting a tar checksum error on Solaris. What's the problem?</q>
       <a>
          <p>The Solaris tar utility you are using does not properly handle files with long pathnames.
          You must use GNU tar (gtar), which handles arbitrarily long pathnames
             and is freely available on every platform on which &xslt4c; is
             supported.  If you don't already have GNU tar installed on your system,
             you can obtain it from the Free Software Foundation
             <jump href="http://www.gnu.org/software/tar/tar.html">
             http://www.gnu.org/software/tar/tar.html</jump>.  For additional
             background information on this problem, see the online manual
             <jump href="http://www.gnu.org/manual/tar/html_node/tar_117.html#SEC112">
             GNU tar and POSIX tar </jump> for the utility.
          </p>
       </a>
    </faq>

 <faq title="&xslt4c; in Apache">
 <q>Is it possible to run &xslt4c; from an Apache server?</q>

 <a><p>A simple Apache module called <link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link> is provided as a sample. It demonstrates how to integrate &xslt4c; with Apache.</p></a>
 </faq>


   <faq title="Is &xslt4c; thread-safe?">

     <q>Is &xslt4c; thread-safe?</q>

     <a>
     <p>Instances of XalanTransformer are not thread-safe; each thread should use its own instance.</p>
     <p>In order to support very efficient use in multi-threaded applications, &xslt4c; is designed to avoid synchronization as much as
      possible. Each thread of execution is required to have its own set of "support" objects that contain the state of the
      transformation.  Accordingly, no synchronization is required when multiple threads are executing.</p>

      <p>Parsed ("compiled") stylesheets (see <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>) and parsed
       source documents may be freely shared by multiple threads of execution without worrying
       about providing synchronized access to them. The <em>only</em> exception to this rule: You use XercesParserLiaison to parse a
       document after calling XercesParserLiaison::setBuildBridgeNodes(false) or XercesParserLiaison::setThreadSafe(false). In this case,
       the document <em>cannot</em> be shared by multiple threads of execution. For reasons of performance, we do not recommend the use of
       XercesParserLiaison, so this should not be an issue for most applications.</p>

      <p>All other objects in &xslt4c; are <em>not</em> thread-safe. Each thread must have its own instance of each object.</p>

      <p>See the <link idref="samples" anchor="threadsafe">ThreadSafe</link> sample program for more information.</p></a>
   </faq>

   <faq title="What can I do to speed up transformations?">

     <q>What can I do to speed up transformations?</q>

     <a><p>To maximize performance, here are some suggestions for you to keep in mind as you set up your applications:</p><ul>
     <li>Use a compiled stylesheet when you expect to use the stylesheet more than once.<br/><br/></li>
     <li>Set up your stylesheets to function efficiently.<br/><br/></li>
        <ul>
          <li>Don't use "//" (descendant axes) patterns near the root of a large document.<br/><br/></li>
          <li>Use xsl:key elements and the key() function as an efficient way to retrieve node sets.<br/><br/></li>
          <li>Where possible, use pattern matching rather than xsl:if or xsl:when statements.<br/><br/></li>
          <li>xsl:for-each is fast because it does not require pattern matching.<br/><br/></li>
          <li>Keep in mind that xsl:sort prevents incremental processing.<br/><br/></li>
          <li>When you create variables, &lt;xsl:variable name="fooElem" select="foo"/&gt; is usually faster than
          &lt;xsl:variable name="fooElem"&gt;&lt;xsl:value-of-select="foo"/&gt;&lt;/xsl:variable&gt;.<br/><br/></li>
          <li>Be careful using the last() function.<br/><br/></li>
          <li>The use of index predicates within match patterns can be expensive.<br/><br/></li>
        </ul>
     </ul></a>
   </faq>

   	<faq title="Stylesheet validation">
 		<q>Can I validate an XSL stylesheet?</q>
 		<a>
       <p>An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, but you probably will have
       to write a custom DTD for the purpose.</p>
       <p>The XSLT Recommendation includes a <jump href="http://www.w3.org/TR/xslt#dtd">DTD Fragment
       for XSL Stylesheets</jump> with some indications of what you need to do to create a complete DTD for a given
       stylesheet. Keep in mind that stylesheets can include literal result elements and produce output that is not valid
       XML.</p>
       <p>You can use the xsl:stylesheet doctype defined in xsl-html40s.dtd for stylesheets that generate HTML.</p>
 		</a>
 	</faq>

         <faq title="What does the XalanDOMException HIERARCHY_REQUEST_ERR mean?">
       <q>What does the XalanDOMException HIERARCHY_REQUEST_ERR mean?</q>
       <a>
         <p>It means that an attempt was made to add a node to a DOM that would create
           an invalid structure.  For example, text nodes are not allowed as children
           of the document node.</p>

           <p>This is a common error when attempting to transform to DOM.
           Source documents and stylesheets that might produce valid serialized XML
           might not produce value DOM.  The usual suspect is text nodes being
           generated before the document element is generated.</p>
           <p>If you think you have seen this error because of a bug in Xalan-C++'s source tree
           implementation, please post a bug report on Bugzilla, and attach a minimal source document
           and stylesheet that produce the problem to the bug report.</p>
       </a>
     </faq>


 <faq title="Patches">
 <q>Who do I submit patches to?</q>
 <a><p>Your contributions are much appreciated! Please e-mail your patches to <human-resource-ref idref="xalandev"/>.</p></a>
 </faq>

 </faqs>
	<?xml version="1.0" standalone="no"?>
	<!DOCTYPE faqs SYSTEM "../../style/dtd/faqs.dtd">

	<faqs title="Frequently asked questions">

	<faq title="Where do I go to learn about XSLT">
	<q>Where do I go to learn about XSLT?</q>

	<a><p>The definitive sources are the W3C XSLT and XPath recommendations: <resource-ref idref="XSLT"/> and
	<resource-ref idref="XPath"/>.</p>
	<p>For general questions not specific to &xslt4c;, see Dave Pawson's <resource-ref idref="dpawsonxslfaq"/> and Michael Kay's
	<jump href="http://www.wrox.com/Consumer/Store/Details.asp?ISBN=1861003129">XSLT Programmer's Reference</jump>.</p>
	<p>For a brief listing of tutorials, discussion forums, and other materials, see <link idref="overview"
	anchor="uptospeed">Getting up to speed with XSLT</link>.</p></a>
	</faq>

	<faq title="Questions"><q>Where can I ask question?</q>

	<a><p>For generic questions about XSL stylesheets and transformations, use the <jump href="http://www.mulberrytech.com/xsl/xsl-list/">XSL-List -- Open Forum on XSL</jump> hosted by Mulberry Technologies. There is an archive that can be searched as well. Specific questions about &xslt4c; can be asked on the Xalan-dev list. Please review this document and the archives before posting new questions.</p>

	<p>For specific questions on &xslt4c;, see xalan-dev@xml.apache.org on <jump href="http://archive.covalent.net/">http://archive.covalent.net/</jump>.</p>
	</a>
	</faq>

	<faq title="What is &xml4c;?">
	<q>What is &xml4c; and why do I need it?</q>

	<a><p>&xml4c; is a validating XML parser written in a portable subset of C++. &xml4c; makes it easy to give your application the ability to read and write XML data. Like &xslt4c;, &xml4c; is available from the Apache XML site: http://xml.apache.org/xerces-c/index.html</p><!--xml4cNote--></a>
	</faq>


	<faq title="Which version of Xerces should I be using?">
	<q>Which version of Xerces should I be using?</q>

	<a><p>The &xslt4c; release notes includes information about the &xml4c; release with which the &xslt4c; release has been coordinated and tested. See <link idref="readme" anchor="status">Status</link></p><!--xml4cNote--></a>
	</faq>

	<faq title="Problems with samples in Windows">
	<q>I have encountered problem executing the &xslt4c; sample applications after rebuilding them under Win32 Environment (Windows NT 4.0, SP3).
	When I tried to execute the sample, I receive the error message "Debug Assertion Failed! ... Expression: _BLOCK_TYPE_IS_VALID(pHead->nBlockUse)".</q>

	<a><p>You may be mixing debug and release versions of executables and libraries. In other words, if you are compiling the sample for debug, then you should link with the debug version of the &xslt4c; and &xml4c; libraries and run with the debug version of the dynamic link libraries.</p><anchor name="build"/><p/></a>
	</faq>

	<faq title="Building on Windows">
	<q>What do I need to rebuild &xslt4c; on Windows?</q>

	<a><p>To build &xslt4c; on Windows, you need &xml4c; and MS Visual C++ 6.0 installed with Service Pack 3 for Visual C++ and Visual Studio. You should also apply the bug fixes for the C++ standard library that shipped with Visual C++ 6.0. These fixes are available from the Dinkumware site: <jump href="http://www.dinkumware.com/vc_fixes.html">http://www.dinkumware.com/vc_fixes.html</jump>.</p>
	<p>For more details, see <link idref="readme" anchor="win32">Steps for doing a Windows build</link>.</p></a>
	</faq>

	<faq title="Building on UNIX">
	<q>What do I need to rebuild &xslt4c; on UNIX?</q>

	<a><p>To build &xslt4c; on supported UNIX platforms, you need &xml4c; and a supported C++ compilers (see the table below). If your compiler does not support the STL or its implementation is old, you must install the STLPort.</p>
	<p>For more details see: http://xml.apache.org/xalan-c/readme.html#unix</p>
	<table>
	<tr>
	<th>Platform - Operating System</th>
	<th>Compilers</th>
	<th>STLPort Required</th>
	</tr>
	<tr>
	<td>AIX 4.3</td>
	<td>IBM C and C++ for AIX 5.02</td>
	<td>No</td>
	</tr>
	<tr>
	<td>Solaris 2.6</td>
	<td>[Workshop 4.2]</td>
	<td>Yes</td>
	</tr>
	<tr>
	<td>HP/UX 11.0</td>
	<td>aCC A.03.27</td>
	<td>No</td>
	</tr>
	<tr>
	<td>Red Hat Linux 6.1</td>
	<td>egcs-2.91.66 and glibc-2.1.2-11</td>
	<td>No</td>
	</tr>
	</table>
	<p>For more details see: <link idref="readme" anchor="unix">Steps for doing a UNIX build</link>.</p>
	</a></faq>

	<faq title="STLPort">
	<q>What is STLPort and why do I need it?</q>

	<a><p>The Standard Template Library, or STL, is a C++ library of container classes, algorithms, and iterators; it provides many of the basic computer science algorithms and data structures. &xslt4c; implementation uses the STL. STLport ports SGI STL to any platform possible and provides all necessary wrap-ups installed. If your compiler does not support the STL or its implementation is out of date, you will need to install the STLPort.</p>

	<p>The STLPort version 4.0 for download from the site: <jump href="http://www.stlport.org/">http://www.stlport.org/</jump>.</p>

	<p>For more details on the STL, see: <jump href="http://www.sgi.com/tech/stl/stl_introduction.html">http://www.sgi.com/tech/stl/stl_introduction.html</jump>.</p></a>
	</faq>

	<faq title="ICU">
	<q>What is ICU and why do I need it?</q>

	<a><p>The International Components for Unicode(ICU) is a C and C++ library that provides robust and full-featured Unicode support on a wide variety of platforms. &xslt4c; uses the ICU to extend support for encoding, number formatting, and sorting.</p>
	<p>The ICU is available for download from <jump href="http://oss.software.ibm.com/developerworks/opensource/icu/project/index.html">http://oss.software.ibm.com/developerworks/opensource/icu/project/index.html</jump>.</p>
	<p>For more details see: <link idref="usagepatterns" anchor="icu">Using the International Components for Unicode (ICU)</link>.</p><!--icuNote--><anchor name="gnutar"/><p/></a>
	</faq>

	<faq title="A tar checksum error on Solaris">
	<q>I am getting a tar checksum error on Solaris. What's the problem?</q>
	<a>
	<p>The Solaris tar utility you are using does not properly handle files with long pathnames.
	You must use GNU tar (gtar), which handles arbitrarily long pathnames
	and is freely available on every platform on which &xslt4c; is
	supported. If you don't already have GNU tar installed on your system,
	you can obtain it from the Free Software Foundation
	<jump href="http://www.gnu.org/software/tar/tar.html">
	http://www.gnu.org/software/tar/tar.html</jump>. For additional
	background information on this problem, see the online manual
	<jump href="http://www.gnu.org/manual/tar/html_node/tar_117.html#SEC112">
	GNU tar and POSIX tar </jump> for the utility.
	</p>
	</a>
	</faq>

	<faq title="&xslt4c; in Apache">
	<q>Is it possible to run &xslt4c; from an Apache server?</q>

	<a><p>A simple Apache module called <link idref="samples" anchor="apachemodulexslt">ApacheModuleXSLT</link> is provided as a sample. It demonstrates how to integrate &xslt4c; with Apache.</p></a>
	</faq>


	<faq title="Is &xslt4c; thread-safe?">

	<q>Is &xslt4c; thread-safe?</q>

	<a>
	<p>Instances of XalanTransformer are not thread-safe; each thread should use its own instance.</p>
	<p>In order to support very efficient use in multi-threaded applications, &xslt4c; is designed to avoid synchronization as much as
	possible. Each thread of execution is required to have its own set of "support" objects that contain the state of the
	transformation. Accordingly, no synchronization is required when multiple threads are executing.</p>

	<p>Parsed ("compiled") stylesheets (see <link idref="usagepatterns" anchor="compiled">Compiling stylesheets</link>) and parsed
	source documents may be freely shared by multiple threads of execution without worrying
	about providing synchronized access to them. The <em>only</em> exception to this rule: You use XercesParserLiaison to parse a
	document after calling XercesParserLiaison::setBuildBridgeNodes(false) or XercesParserLiaison::setThreadSafe(false). In this case,
	the document <em>cannot</em> be shared by multiple threads of execution. For reasons of performance, we do not recommend the use of
	XercesParserLiaison, so this should not be an issue for most applications.</p>

	<p>All other objects in &xslt4c; are <em>not</em> thread-safe. Each thread must have its own instance of each object.</p>

	<p>See the <link idref="samples" anchor="threadsafe">ThreadSafe</link> sample program for more information.</p></a>
	</faq>

	<faq title="What can I do to speed up transformations?">

	<q>What can I do to speed up transformations?</q>

	<a><p>To maximize performance, here are some suggestions for you to keep in mind as you set up your applications:</p><ul>
	<li>Use a compiled stylesheet when you expect to use the stylesheet more than once.<br/><br/></li>
	<li>Set up your stylesheets to function efficiently.<br/><br/></li>
	<ul>
	<li>Don't use "//" (descendant axes) patterns near the root of a large document.<br/><br/></li>
	<li>Use xsl:key elements and the key() function as an efficient way to retrieve node sets.<br/><br/></li>
	<li>Where possible, use pattern matching rather than xsl:if or xsl:when statements.<br/><br/></li>
	<li>xsl:for-each is fast because it does not require pattern matching.<br/><br/></li>
	<li>Keep in mind that xsl:sort prevents incremental processing.<br/><br/></li>
	<li>When you create variables, <xsl:variable name="fooElem" select="foo"/> is usually faster than
	<xsl:variable name="fooElem"><xsl:value-of-select="foo"/></xsl:variable>.<br/><br/></li>
	<li>Be careful using the last() function.<br/><br/></li>
	<li>The use of index predicates within match patterns can be expensive.<br/><br/></li>
	</ul>
	</ul></a>
	</faq>

	<faq title="Stylesheet validation">
	<q>Can I validate an XSL stylesheet?</q>
	<a>
	<p>An XSL stylesheet is an XML document, so it can have a DOCTYPE and be subject to validation, but you probably will have
	to write a custom DTD for the purpose.</p>
	<p>The XSLT Recommendation includes a <jump href="http://www.w3.org/TR/xslt#dtd">DTD Fragment
	for XSL Stylesheets</jump> with some indications of what you need to do to create a complete DTD for a given
	stylesheet. Keep in mind that stylesheets can include literal result elements and produce output that is not valid
	XML.</p>
	<p>You can use the xsl:stylesheet doctype defined in xsl-html40s.dtd for stylesheets that generate HTML.</p>
	</a>
	</faq>

	<faq title="What does the XalanDOMException HIERARCHY_REQUEST_ERR mean?">
	<q>What does the XalanDOMException HIERARCHY_REQUEST_ERR mean?</q>
	<a>
	<p>It means that an attempt was made to add a node to a DOM that would create
	an invalid structure. For example, text nodes are not allowed as children
	of the document node.</p>

	<p>This is a common error when attempting to transform to DOM.
	Source documents and stylesheets that might produce valid serialized XML
	might not produce value DOM. The usual suspect is text nodes being
	generated before the document element is generated.</p>
	<p>If you think you have seen this error because of a bug in Xalan-C++'s source tree
	implementation, please post a bug report on Bugzilla, and attach a minimal source document
	and stylesheet that produce the problem to the bug report.</p>
	</a>
	</faq>


	<faq title="Patches">
	<q>Who do I submit patches to?</q>
	<a><p>Your contributions are much appreciated! Please e-mail your patches to <human-resource-ref idref="xalandev"/>.</p></a>
	</faq>

	</faqs>