cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: DocbookTransformation
Date Wed, 26 Jan 2005 11:11:23 GMT
   Date: 2005-01-26T03:11:23
   Editor: GabrieleDomenichini
   Wiki: Cocoon Wiki
   Page: DocbookTransformation
   URL: http://wiki.apache.org/cocoon/DocbookTransformation

   no comment

Change Log:

------------------------------------------------------------------------------
@@ -1,211 +1,4 @@
 = Using Docbook and the stylesheet by Norman Walsh in Cocoon  =
 
 == Overview  ==
-If you want to use Docbook as the system to write important structured documents and you
want to transform them to PDF or to HTML with the stylesheets already prepared and maintained
by Norman Walsh 
-on the [http://docbook.sourceforge.net/projects/xsl/index.html official docbook repository
], you could meet some problem. Here is what I did to solve them.[[BR]] 
-Xalan (the default xslt processor of Cocoon) has some limitation in using Norman Walsh's
stylesheets inside the pipelines. Norman Walsh recently has [http://docbook.sourceforge.net/release/xsl/current/doc/publishing.html.html#d0e59
written ] : 
-
-''..The following engines are not currently recommended for use with the !DocBook XSL stylesheets:
..Xalan..'' 
-
-On the other hand, using Saxon, I personally have obtained incomplete transformations (I
lost all the sec1/title part in the result pdf document!). To solve this problem you have
to choices: 
- *  Use saxon 6.5.2 (the version suggested by the site) and hack the jar to make it use xerces
as parser 
- *  Use saxon 7.2 and following wich use the jaxp parser (they are not considerated the official
version). 
-
-== Version  ==
-At the time of this writing, this Snippet was tested against: Cocoon version 2.0.3, Xalan
4.0.5, Saxon 6.5.2, Tomcat 4.0.4.[[BR]] 
-I have also included the differences you have to apply if you want to follow the way of using
Saxon 7.3.1 which in my environment works. 
-It will remain valid as long as Xalan has problems transforming docbook files with Norman
Walsh's stylesheets 
-=== Obtaining the drivers  ===
-Download the xslt processor from [http://saxon.sourceforge.net/ Saxon site ].[[BR]] 
-Open the zip file with an utiliy and estract the saxon.jar file into $COCOON/WEB-INF/lib
directory (or an other directory in which cocoon can read the classes).[[BR]] 
-
-== cocoon.xconf  ==
-To make Saxon available in your sitemap you have to make pretty much the same steps explained
in the [http://xml.apache.org/cocoon/snippet/snippet-xslt-options.html XSLT snippet] in which
these arguments are treated deeper. 
-Here you have the xslt-processor element declaring the default xslt processor behaviour.

-{{{ 
-<xslt-processor class="org.apache.cocoon.components.xslt.XSLTProcessorImpl" 
-logger="core.xslt-processor"> 
-<parameter name="use-store" value="true"/> 
-<parameter name="incremental-processing" value="true"/> 
-</xslt-processor> 
-}}} 
-
-'''Saxon 6.5.2'''[[BR]] 
-If you want to add the possibility to use an other xslt processor (Saxon 6.5.2 in this example)
we have to add an additional component (Add it immediately under the xslt-processor element
so you remember why it's there). If you use this version you must hack the processor to make
it use the xerces parser (explained after). 
-{{{ 
-<component 
-role="org.apache.cocoon.components.xslt.XSLTProcessor/Saxon" 
-class="org.apache.cocoon.components.xslt.XSLTProcessorImpl" 
-logger="core.xslt-processor"> 
-<parameter name="use-store" value="true"/> 
-<parameter name="incremental-processing" value="false"/> 
-<parameter name="transformer-factory" value="com.icl.saxon.TransformerFactoryImpl"/>

-</component> 
-}}} 
-
-''Hacking Saxon (only with 6.5.2)''[[BR]] 
-
-FredericGlorieux It seems to me that the xml parser problem is encountered in resolution
of entities for the localisation messages {your xsl-docbook distrib}/common/l10n.xml, include
by {your xsl-docbook distrib}/common/l10n.xsl# <xsl:param name="l10n.xml" select="document('../common/l10n.xml')"/>.
With the last saxon6, in core.log jetty says "java.net.MalformedURLException: no protocol:
en.xml" (and same for all localisations). Fast workaround (and not so bad practice in fact,
because of the size of the file), edit your own l10n.xml with the localisations you need,
instead of the entities.
-
-
-I have received a comment which says that normally Saxon use Xerces. I really can't tell
anything about it but what I'm sure of is that on my system the only way to make the thing
work is to "patch" Saxon.jar to make it use Xerces this way: 
-Change the content of 
-META-INF/services/javax.xml.parsers.SAX!ParserFactory from 
-com.icl.saxon.aelfred.SAX!ParserFactoryImpl to 
-org.apache.xerces.jaxp.SAX!ParserFactoryImpl. This tells Saxon to use xerces instead of aelfred
as parser.[#1][[BR]] 
-Don't be worried it is not so complicated: you have to extract the file 
-(javax.xml.parsers.SAX!ParserFactory) from saxon.jar edit it (is a text file) 
-and to put it again in the same place in saxon.jar 
-
-'''Saxon 7.5.2'''[[BR]] 
-
-FredericGlorieux Try before an offline transformation with you prefered saxon7.jar. You will
have lots of warns because of bugs in you docbook-xsl distrib, essentially, confusion between
strings and numbers in comparisons, especially in the generated titlepage.templates.xsl.
-
-If you want to use instead Saxon 7.5.2 the only thing to change is the parameter "transformer-factory"
and remember that in this case you don't have to change the parser used by Saxon. 
-{{{ 
-<component 
-role="org.apache.cocoon.components.xslt.XSLTProcessor/Saxon" 
-class="org.apache.cocoon.components.xslt.XSLTProcessorImpl" 
-logger="core.xslt-processor"> 
-<parameter name="use-store" value="true"/> 
-<parameter name="incremental-processing" value="false"/> 
-<!-- the path to the transformer-factory has changed ... --> 
-<parameter name="transformer-factory" value="net.sf.saxon.TransformerFactoryImpl"/>

-</component> 
-}}} 
-
-== sitemap.xmap  ==
-=== components  ===
-In the sitemap.xmap we have to add the new transformer which is identified by the _xsl-processor-role_

-{{{ 
-<map:components> 
-
-<!-- other map:components here --> 
-
-<map:transformers> 
-
-<!-- other map:transformers here --> 
-<!-- Xalan transformer (no xslt-processor-role) --> 
-<map:transformer name="xslt-xalan" pool-grow="2" pool-max="32" pool-min="8" 
-src="org.apache.cocoon.transformation.TraxTransformer"> 
-<use-request-parameters>false</use-request-parameters> 
-<use-browser-capabilities-db>false</use-browser-capabilities-db> 
-</map:transformer> 
-
-<!-- Saxon transformer look at the new element: xslt-processor-role --> 
-<map:transformer name="xslt-saxon" pool-grow="2" pool-max="32" pool-min="8" 
-src="org.apache.cocoon.transformation.TraxTransformer"> 
-<use-request-parameters>false</use-request-parameters> 
-<use-browser-capabilities-db>false</use-browser-capabilities-db> 
-<xslt-processor-role>Saxon</xslt-processor-role> 
-</map:transformer> 
-
-<!-- other map:transformers here --> 
-
-</map:transformers> 
-
-<!-- other map:components here --> 
-
-</map:components> 
-}}} 
-=== pipelines  ===
-Now in the pipeline of your sitemap.xmap you can decide whether to use Saxon or Xalan for
xslt processing 
-
-{{{ 
-<map:pipeline> 
-
-<!-- using saxon --> 
-<map:match pattern="*.pdf"> 
-<map:generate src="docs/{1}.xml"/> 
-<map:transform type="xslt-saxon" src="stylesheets/page2fo.xsl"/> 
-<!-- If you want to use xalan you have to set type="xslt-xalan" --> 
-<map:serialize type="fo2pdf"/> 
-</map:match> 
-
-</map:pipeline> 
-}}} 
-== Comments  ==
-Care to comment on this Snippet? Got another tip? Help keep this Snippet relevant by passing
along any useful feedback to the mailto:cocoon-users@xml.apache.org or directly down here.

-
------ 
-
-== Rate the article  ==
-Interesting?[[BR]]
-x: no[[BR]]xx: mmh.. something[[BR]]xxx: yes[[BR]]xxxx: What I was waiting for 
-||'''rate'''||'''judge'''||||
-||xxxx||[:Gabridome] ;-)||
-
-== Readers comments  ==
-
-[[Anchor(1)]]Since version 7.2 of Saxon you no longer need to "hack" the JAR since it uses
the JAXP API by default. -- !AnonymousDonor 
-
-Might be worthwhile to have links to a concoon.xconf and sitemap.xmap file which implement
the dual xlan/saxon usage described above. I followed the instructions and Cocoon no longer
works, it can't find the components xslt, xslt-xalan or xslt-saxon. 
-
-Also, in the cocoon.xconf section above there is mention of an "XSLT snippit" it would be
worth while to include a link to it. -- !PaulGitings 
-
-Example(s) of the serving !DocBook Content on Cocoon:
- 1.[http://www.xml-dev.com:8080/cocoon/mount/docbook/Apache-WebDAV-LDAP-HOWTO.html] 
- 1.[http://www.xml-dev.com:8080/cocoon/mount/docbook/openjade.html]
-
-
-[[Anchor(2)]]More hints:
- * It is necessary to enable FOP extensions to render Docbook to PDF, use a custom stylesheet
- * PNG format is not supported out of the box. [http://java.sun.com/products/java-media/jai
Download and install JAI for PNG support]
- * references to image files must be absolute ([http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15316
see Bug 15316])
-
-The following snippets might be helpful:
-custom stylesheet (custom.xsl)
-{{{
-<?xml version="1.0"?>
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0"
-                xmlns:fo="http://www.w3.org/1999/XSL/Format"
-                exclude-result-prefixes="#default">
-  <!-- link to docbook.xsl-->
-  <xsl:import href="docbook/fo/docbook.xsl"/>
-  <!--~~~~~~~~~~~~-->
-  <!-- enable fop -->
-  <!--~~~~~~~~~~~~-->
-  <xsl:param name="use.extensions">1</xsl:param>
-  <xsl:param name="fop.extensions">1</xsl:param>
-  <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-  <!-- enable admonition graphics -->
-  <!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-  <xsl:param name="admon.graphics">1</xsl:param>
-  <xsl:param name="admon.graphics.extension" select="'.png'"/>
-  <!-- CAUTION: this path must be absolute -->
-  <!-- SEE: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15316 -->
-  <!-- and don't forget the trailing slash -->
-  <xsl:param name="admon.graphics.path" select="'/jetty/webapps/cocoon/docbook/images/'"/>
-</xsl:stylesheet> 
-}}}
-a very simple docbook article (example.xml)
-{{{
-<article>
-	<title>Render Docbook with Cocoon</title>
-	<para>
-		<caution>
-			<para>Use an absolute path for admonition graphics in your custom.xsl 
-                        and don&#39;t forget to install JAI to render PNG images.</para>
-			<figure>
-				<title>image example</title>
-				<!-- the fileref must be an absolute path -->
-				<graphic fileref="/home/rockhead/images/example.gif"/>
-			</figure>
-		</caution>
-	</para>
-</article>
-}}}
-a sitemap snippet
-{{{
-<map:match pattern="example.pdf">
-		<map:generate src="example.xml"/>
-		<map:transform src="custom.xsl" type="xalan"/>
-		<map:serialize type="fo2pdf"/>
-</map:match>
-}}}
-Have a look at the [http://wiki.cocoondev.org/attach?page=DocbookTransformation%2Fexample.pdf
generated PDF file]
-[[BR]]
-[[BR]]
-'''Attachment:''' attachment:article.001.xml [[BR]]
-'''Attachment:''' attachment:example.pdf [[BR]]
+If you want to use Docbook as the system to write important structured documents and you
want to transform them to PDF or to HTML with the styleshee

Mime
View raw message