shannon 2002/08/21 17:43:16 Modified: src/documentation/xdocs/faq faq-xslt.xml Log: added faq for document function Revision Changes Path 1.6 +62 -0 xml-cocoon2/src/documentation/xdocs/faq/faq-xslt.xml Index: faq-xslt.xml =================================================================== RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/faq/faq-xslt.xml,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- faq-xslt.xml 2 Jul 2002 23:16:12 -0000 1.5 +++ faq-xslt.xml 22 Aug 2002 00:43:16 -0000 1.6 @@ -138,5 +138,67 @@ </answer> </faq> +<faq> + <question> +What's "wrong" with use of the document() function in Cocoon? + </question> + + <answer> + <p> +Using the document() function for aggregation in Cocoon may break +Separation of Concerns (SoC). That is, the designers of Cocoon +view inclusion and transformation as different functions, best +handled by separate Cocoon components. Treating them +separately allows you to achieve performance gains and increases +the resusability of your pipelines. + </p> + <p> +Alternatives to the document() in the Cocoon environment include +aggregation or the use of a multi-stage transformation using the +XInclude Transformer. This involves transforming a list of documents +(generated dynamically or statically) by adding xinclude elements which +reference (via xpointer) specific document content, and then transforming +again via the XInclude Transformer, to obtain the desired result. For an example of this, see this <link href="http://marc.theaimsgroup.com/?l=xml-cocoon-users&m=102617106411067&w=2";>email.</link> + </p> + <p> +You'll achieve better performance if you aggregate content prior to transformation. +This allows you to take full advantage of Cocoon's pipeline caching. In contrast, +making dynamic document() calls inside an XSLT within a cached pipeline is problematic. +At this time, Cocoon does not recognize changes in documents (called by the document() function) +until the requested page expires from cache. + </p> + <p> +Understand that the document() function was designed *before* xinclude +with xpointer facilities existed. Had such capabilities been available, +perhaps the document() function, which essentially mimics xinclude and xpointer, +would have never been added to XSLT. + </p> + <p> +Please note that if you must work with your XML files outside of the +Cocoon environment, you may need to use the document() function +in order to utilize the limited capabilities of other pipeline engines. +This includes engines which are not xinclude-capable or which +lack a predefined way to indicate document processing steps. If you +are working with legacy code from non-pipelined engines, you may need to use +the document() function as well, at least initially. + </p> + <p> +If you do use the document() function in Cocoon, you can still observe SoC by +having separate XSLT stylesheets perform inclusion and transformation functions. +For example, you can put multiple XSLT transforms in a pipeline and have the +first one perform inclusion and the second one perform transformation. However, +be mindful of some unresolved caching issues in Cocoon related to the document() function. +At this time, Cocoon is unable to check validity of content included via the document() +function. In addition, the document() function implemented by Xalan is inefficient. See: + http://nagoya.apache.org/bugzilla/show_bug.cgi?id=4257 +Until this bug is fixed, consider using Saxon instead for document() function-related parsing +needs. + </p> + <p> +For other aggregation/inclusion approaches, please stay tuned for XpathDirectoryGenerator (2.1 scratchpad), +as well as Forrest's Libre (currently alpha in the Forrest cvs). + </p> + </answer> + </faq> </faqs>
---------------------------------------------------------------------- In case of troubles, e-mail: [EMAIL PROTECTED] To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
