greenrd 00/10/15 15:40:11
Modified: xdocs faq.xml installing.xml xspprocessor.xml Log: minor docs updates Revision Changes Path 1.20 +42 -3 xml-cocoon/xdocs/faq.xml Index: faq.xml =================================================================== RCS file: /home/cvs/xml-cocoon/xdocs/faq.xml,v retrieving revision 1.19 retrieving revision 1.20 diff -u -r1.19 -r1.20 --- faq.xml 2000/09/27 23:31:07 1.19 +++ faq.xml 2000/10/15 22:40:10 1.20 @@ -162,6 +162,41 @@ <faqsection title="XSP Pages"> + <faq id="xspinsertxml"> + <question>Why does Cocoon escape my XML with &lt; and &gt; when I try to + insert an XML string in an XSP page?</question> + <answer> + <p>This is the correct behaviour, as described in the <connect href="xspprocessor.xml"> + XSP Processor documentation</connect>. To tell Cocoon to include the XML "literally" + into its Document Object Model (so that it is not escaped when it is outputted), + there are two basic options:</p> + + <ol> + <li>The easiest way is to simply replace <code><xsp:expr></code> with + <code><util:include-expr></code> (making sure to declare the util + logicsheet namespace in your <code><xsp:page></code> tag - instructions for + this can be found in the XSP documentation). However this is not necessarily the + most efficient way, because it invokes the installed XML parser to parse the + string into an in-memory representation used throughout Cocoon 1.x called a + <link href="http://www.w3.org/DOM/";>DOM <strong>(Document Object Model)</strong> + </link>. + </li> + <li>It is thus better to generate DOM objects directly. This is outside the scope + of this documentation (except insofar as it documents the specification of + <code><xsp:expr></code>) - see the DOM link above, and also the question on + <jump href="#faq-goodbooks">"good books"</jump>. You can also generate + <code>org.apache.cocoon.framework.XObject</code>s, and return both DOM and SAX, + thus making your code (hopefully) more forward-compatible with Cocoon 2, which will be + SAX-based. (Actually using SAX is not strictly necessary, since DOM can always be + converted to SAX and vice-versa, but you will pay a performance penalty in Cocoon 2 + by using DOM.) + Note that with either of these, you should still use <code><xsp:expr></code>, + <strong>not</strong> <code><util:include-expr></code>. + </li> + </ol> + </answer> + </faq> + <faq id="nocompile"> <question>I keep changing my XSP pages to try and fix a bug, and it never seems to recompile. What gives?</question> @@ -473,10 +508,14 @@ Note that this is <em>not</em> a bug in Cocoon and is completely outside our control.</p> - <note>There is a bug in MS Internet Explorer 5 which even ignores the - question mark. See the + <note>There are bugs in MS Internet Explorer 5.x and/or Acrobat Reader + which even ignore the question mark. See the <link href="http://support.microsoft.com/support/kb/articles/Q177/3/21.ASP";> - Microsoft Knowledge Base</link>.</note> + Microsoft Knowledge Base</link> and + <link href="http://www.adobe.com/support/techdocs/3d76.htm";> + Adobe Support Knowledgebase (1)</link>, + <link href="http://www.adobe.com/support/techdocs/98fe.htm";>(2)</link>. + </note> </answer> </faq> 1.26 +30 -1 xml-cocoon/xdocs/installing.xml Index: installing.xml =================================================================== RCS file: /home/cvs/xml-cocoon/xdocs/installing.xml,v retrieving revision 1.25 retrieving revision 1.26 diff -u -r1.25 -r1.26 --- installing.xml 2000/09/27 23:31:10 1.25 +++ installing.xml 2000/10/15 22:40:11 1.26 @@ -687,6 +687,11 @@ <td>Sun JDK 1.2.2</td> </tr> <tr> + <td>Linux Mandrake 7.0</td> + <td colspan="2">Orion/1.0.3</td> + <td>Sun JDK 1.3.0rc1</td> + </tr> + <tr> <td>SuSE 6.3 Linux</td> <td>Apache 1.3.9</td> <td>Apache JServ 1.1</td> @@ -748,10 +753,22 @@ </tr> <tr> <td>Windows NT 4.0</td> - <td colspan="2">Apache Jakarta Tomcat 3.1 Milestone 1</td> + <td colspan="2">Tomcat 3.1 Milestone 1</td> <td>Sun JDK 1.2.2</td> </tr> <tr> + <td>Windows NT 4.0 SP3</td> + <td>Apache 1.3.12</td> + <td>JServ 1.1.2</td> + <td>Sun JRE 1.2.2</td> + </tr> + <tr> + <td>Windows NT 4.0 SP4</td> + <td>Apache 1.3.12</td> + <td>Tomcat 3.1</td> + <td>Sun JDK 1.3</td> + </tr> + <tr> <td>Windows NT 4.0 SP4</td> <td colspan="2">BEA WebLogic Server 5.1 SP3</td> <td>Sun JDK 1.2.2</td> @@ -775,6 +792,12 @@ <td>Sun JDK 1.2.2</td> </tr> <tr> + <td>Windows NT 4.0 SP6a</td> + <td>Apache 1.3.12</td> + <td>Tomcat 3.1</td> + <td>Sun JDK 1.2.2</td> + </tr> + <tr> <td>Windows 2000 Professional</td> <td>Apache 1.3.12</td> <td>Apache JServ 1.1</td> @@ -818,6 +841,12 @@ <td>Quid Pro Quo 2.1.3</td> <td>ServletExec 2.2</td> <td>Mrj 2.1.4</td> + </tr> + <tr> + <td>Solaris 2.5.1</td> + <td>Apache 1.3.12</td> + <td>Tomcat 3.1</td> + <td>Sun JDK 1.2.2</td> </tr> <tr> <td>Solaris 2.5.1</td> 1.8 +26 -4 xml-cocoon/xdocs/xspprocessor.xml Index: xspprocessor.xml =================================================================== RCS file: /home/cvs/xml-cocoon/xdocs/xspprocessor.xml,v retrieving revision 1.7 retrieving revision 1.8 diff -u -r1.7 -r1.8 --- xspprocessor.xml 2000/09/16 19:06:48 1.7 +++ xspprocessor.xml 2000/10/15 22:40:11 1.8 @@ -369,14 +369,36 @@ and wrapped as <code>Text</code> </li> <li> - Java objects are wrapped as follows: + <code>Node</code>s (which is to say, instances of all subclasses of + <code>org.w3c.dom.Node</code>) are left as-is + if their owner document is the same as the XSP output document, or + cloned if not (in order to change the owner document). Efficiency gains + can be made by always creating Nodes to be inserted with + <code>document</code> as their owner document (although this is probably + what you are doing anyway!). NOTE: You should not insert + objects whose type is <strong>equal</strong> to + <code>Node</code> because this is considered an abstract class - instead, use + Element to insert one element at a time, or DocumentFragment to insert + multiple elements at the same time. (Here "one element" and "multiple + elements" refers to elements at the top level, so <a><b/></a> + still counts as "one element" in this context, but <a/><b/> counts + as two.) + </li> + <li> + All other Java objects are wrapped as follows: <ul> <li> <code>String</code>s are directly wrapped as - <code>Text</code> + <code>Text</code>. <strong>WARNING:</strong> This means that if you try to + insert some XML as a <code>String</code> using <code><xsp:expr></code>, + it will not work! Instead, you will need to <em>either</em> use + <code><util:include-expr></code>, <em>or</em> build <code>XObject</code>s + or <code>org.w3c.dom.Node</code>s instead - please read the + <link href="faqs.html#faq-xspinsertxml">FAQ</link> on this before asking + questions about it. </li> <li> - Arrays are wrapped as <code>DocumentFragments</code> + Arrays are wrapped as <code>DocumentFragment</code>s and each element is recursively applied these same transformation rules. </li> @@ -386,7 +408,7 @@ and subsquently wrapped as <code>Text</code>. Note that some types may not provide a suitable string representation, so they may require a - more elaborate expression + more elaborate, explicit expression. </li> </ul> </li>
