vgritsenko 2003/03/12 17:29:32
Modified: src/documentation/xdocs/userdocs/serializers
pdf-serializer.xml
Log:
Apply patch #17930: Update pdf serializer doc
Revision Changes Path
1.2 +60 -54
cocoon-2.1/src/documentation/xdocs/userdocs/serializers/pdf-serializer.xml
Index: pdf-serializer.xml
===================================================================
RCS file:
/home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/serializers/pdf-serializer.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- pdf-serializer.xml 9 Mar 2003 00:08:24 -0000 1.1
+++ pdf-serializer.xml 13 Mar 2003 01:29:32 -0000 1.2
@@ -1,4 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
+
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
@@ -8,91 +9,89 @@
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="[EMAIL PROTECTED]"/>
- <person name="John Morrison" email="[EMAIL PROTECTED]"/>
+ <person name="John Morrison" email="[EMAIL PROTECTED]"/>
</authors>
<abstract>This document describes the pdf serializer of Cocoon.</abstract>
</header>
<body>
<s1 title="PDF Serializer">
- <p>The pdf serializer takes fo xml events as input. By using the
- FOP project it creates pdf out of the sax events.</p>
- <p>This serializer is optional and requires the fop package
- in the lib directory when building cocoon 2. However,
- the distribution includes this package already.</p>
+ <p>The PDF serializer takes
+ <link href="http://www.w3.org/TR/xsl";>XSL FO</link> SAX events as
input.
+ By using the <link href="http://xml.apache.org/fop/";>FOP</link>
project
+ it creates PDF out of the SAX events.</p>
+ <p>This serializer is optional and requires the FOP package in the lib
+ directory when building Cocoon 2. However, the distribution includes
+ this package already.</p>
<ul>
<li>Name : fo2pdf</li>
<li>Class: org.apache.cocoon.serialization.FOPSerializer</li>
- <li>Cacheable: yes.</li>
+ <li>Cacheable: yes</li>
</ul>
</s1>
<s1 title="FOP and Embedding Fonts">
- <p>Dynamically generating a pdf file (with embeded fonts) in Cocoon
+ <p>Dynamically generating a PDF file (with embedded fonts) in Cocoon
is basically 8 steps:</p>
<ol>
<li>Create the font(s) metric file(s).</li>
- <li>Create a custom configuration file for FOP (Cocoons PDF renderer)
+ <li>Create a custom configuration file for FOP (Cocoons PDF renderer),
which tells it what fonts are available and where to find them.</li>
<li>Create your xml (left as an exercise for the reader ;)</li>
<li>Create your xslt (again, up to you)</li>
<li>In the sitemap, tell the fo2pdf serializer where your custom
configuration file is located.</li>
- <li>Add a match for your pdf (I'm sure you can do the rest...).</li>
+ <li>Add a match for your PDF (I'm sure you can do the rest...).</li>
<li>Start Cocoon.</li>
- <li>Request your pdf.</li>
+ <li>Request your PDF.</li>
</ol>
<p>Easy yeah? OK. Step-by-step...</p>
<s2 title="Create the font(s) metric file(s).">
- <note>All java calls have nothing else in the
- classpath OR ext directory also, instructions which have wrapped
- should be entered as one single instruction.</note>
+ <note>All java calls have nothing else in the classpath or ext
directory.
+ Also, instructions which have wrapped should be entered as one
single
+ instruction.</note>
<p>The instruction to generate a font metric file is:</p>
<p>Windows:</p>
<source>
-java -cp fop-0.20.3rc.jar;xercesImpl-2.0.0.jar;xml-apis.jar \
+$ cd %PATH_TO_COCOON%\lib
+$ java -cp optional\fop-0.20.4.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
org.apache.fop.fonts.apps.TTFReader \
%PATH_TO_FONT% %PATH_TO_METRICS_DIR%\%FONT_NAME%.xml
</source>
<p>Unix:</p>
<source>
-java -cp fop-0.20.3rc.jar;xercesImpl-2.0.0.jar;xml-apis.jar \
+$ cd $PATH_TO_COCOON/lib
+$ java -cp optional/fop-0.20.4.jar;core/xercesImpl-2.0.0.jar;core/xml-apis.jar \
org.apache.fop.fonts.apps.TTFReader \
$PATH_TO_FONT $PATH_TO_METRICS_DIR/$FONT_NAME.xml
</source>
- <note>These jars are not all in the same directory. Either provide
- path information (fop is in optional, the other two in core) or
- copy them into the same directory.</note>
-
- <p>For the sake of this tutorial, I'm going to be using windows,
- converting the Arial family of fonts and storing the metrics files in
- the location <code>D:\fop-fonts</code>.</p>
- <p>My ttf files are located in <code>C:\WINNT\Fonts</code>. If you are
- running on linux/windows 9x/windows ME please alter as
- appropriate.</p>
- <note>I normally use Cygwin; a unix shell
- environment which runs on windows. If I slip some unix into here,
- please excuse me (although I'd welcome the feedback...).</note>
+ <s3 title="Example: Create the Arial metric files.">
+ <p>For the sake of the rest of this tutorial, I'm going to be using
+ Windows NT, converting the Arial family of fonts and storing the
metrics
+ files in the location <code>D:\fop-fonts</code>.</p>
+ <p>My TTF files are located in <code>C:\WINNT\Fonts</code>. If you are
+ running on Linux/Windows 9x/ME/2000/XP please alter as
appropriate.</p>
+ <note>I normally use Cygwin; a Unix shell environment which runs on
Windows.
+ If I slip some Unix into here, please excuse me (although I'd
welcome
+ the feedback...).</note>
- <s3 title="Generating the Arial metrics">
- <p>Start a command session (as appropriate to your env) then change
+ <p>Start a command session (as appropriate to your env), then change
to Cocoon libs directory.</p>
- <source>$ cd <![CDATA[<cocoon>\]]>lib</source>
- <p>create the metrics directory (D:\fop-fonts)</p>
+ <source>$ cd %PATH_TO_COCOON%\lib</source>
+ <p>Create the metrics directory (D:\fop-fonts)</p>
<source>$ mkdir d:\fop-fonts</source>
- <p>create the metrics for arial.ttf, arialb.ttf, arialbi.ttf,
- ariali.ttf</p>
+ <p>Create the metrics for arial.ttf, arialb.ttf, arialbi.ttf,
ariali.ttf</p>
<source>
-$ java -cp optional\fop-0.20.3rc.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
+$ java -cp optional\fop-0.20.4.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
org.apache.fop.fonts.apps.TTFReader \
C:\WINNT\Fonts\arial.ttf D:\fop-fonts\arial.ttf.xml
-$ java -cp optional\fop-0.20.3rc.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
+$ java -cp optional\fop-0.20.4.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
org.apache.fop.fonts.apps.TTFReader \
C:\WINNT\Fonts\arialb.ttf D:\fop-fonts\arialb.ttf.xml
-$ java -cp optional\fop-0.20.3rc.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
+$ java -cp optional\fop-0.20.4.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
org.apache.fop.fonts.apps.TTFReader \
C:\WINNT\Fonts\arialbi.ttf D:\fop-fonts\arialbi.ttf.xml
-$ java -cp optional\fop-0.20.3rc.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
+$ java -cp optional\fop-0.20.4.jar;core\xercesImpl-2.0.0.jar;core\xml-apis.jar \
org.apache.fop.fonts.apps.TTFReader \
C:\WINNT\Fonts\ariali.ttf D:\fop-fonts\ariali.ttf.xml
</source>
@@ -107,7 +106,7 @@
move it ;)</p>
<p>I also find it useful to retain the <code>.ttf</code> as it is also
possible to add other types of fonts (if you want to read the FOP
- docs) and the ttf tells me where to locate the font.</p>
+ docs) and the <code>.ttf</code> tells me where to locate the font.</p>
<source><![CDATA[
<configuration>
<fonts>
@@ -136,35 +135,42 @@
]]></source>
<p>There are other things you can add to this file, look at the FOP
documentation for further information.</p>
- <p>If you are wondering why each font has been added twice it's to do
- with the font lookup. If the font is specified as 'Arial' and the
- weight is 'bold' then FOP searches for a
- <code><![CDATA[<font-triplet/>]]></code> which matches then uses
- the parent <code><![CDATA[<font/>]]></code> tag to get the actual
- font information. If the font is specified as 'ArialMT' (it's proper
- name) it will still work. Think of it as an alias capability.</p>
+ <p>If you are wondering why each font has been added twice, it has to do
+ with the font lookup. If the font is specified as 'Arial' and the
+ weight is 'bold' then FOP searches for a matching
+ <code><![CDATA[<font-triplet/>]]></code>, then uses the parent
+ <code><![CDATA[<font/>]]></code> tag to get the actual font
information.
+ If the font is specified as 'ArialMT' (it's proper name) it will still
+ work. Think of it as an alias capability.</p>
</s2>
<s2 title="Sitemap and fo2pdf serializer.">
- <p>All that remains is to tell the serializer where your config file is
- located. Find the line in your sitemap which looks
- like:</p>
+ <p>All that remains is to tell the serializer, where your config file is
+ located. Find the line in your sitemap which looks like:</p>
<source><![CDATA[
<map:serializer name="fo2pdf"
src="org.apache.cocoon.serialization.FOPSerializer"
mime-type="application/pdf"/>
]]></source>
- <p>and replace it with...</p>
+ <p>and replace it with:</p>
<source><![CDATA[
<map:serializer name="fo2pdf"
src="org.apache.cocoon.serialization.FOPSerializer"
mime-type="application/pdf">
- <user-config src="D:/fop-fonts/config.xml"/>
+ <user-config>D:/fop-fonts/config.xml</user-config>
</map:serializer>
]]></source>
+ <p>You can use absolute paths like above or relative ones. The relative
+ paths will be resolved to the sitemap's directory. Furthermore it's
possible
+ to use Cocoon protocols like <code>cocoon://</code> or
+ <code>context://</code>.</p>
+ <note>In an older version of Cocoon (2.0.3 and earlier) the config file
+ location was specified by using an attribute 'src' on
+ <![CDATA[<user-config/>]]>. If you still have this in your sitemap,
it's
+ recommended to change it to the above provided configuration.</note>
</s2>
- <p>And that's it. Oh, one final thing to remember: the cache isn't aware
+ <p>And that's it. Oh, one final thing to remember: the cache isn't aware
of your config file; <strong>always</strong> delete your cache-dir
after modifying your config file.</p>
</s1>
</body>
-</document>
+</document>
\ No newline at end of file
