Author: sjur
Date: Tue Sep 2 06:08:27 2008
New Revision: 691232
URL: http://svn.apache.org/viewvc?rev=691232&view=rev
Log:
Updated the plugin documentation to provide info about the new settable
properties.
Modified:
forrest/trunk/plugins/org.apache.forrest.plugin.output.pdf/src/documentation/content/xdocs/index.xml
Modified:
forrest/trunk/plugins/org.apache.forrest.plugin.output.pdf/src/documentation/content/xdocs/index.xml
URL:
http://svn.apache.org/viewvc/forrest/trunk/plugins/org.apache.forrest.plugin.output.pdf/src/documentation/content/xdocs/index.xml?rev=691232&r1=691231&r2=691232&view=diff
==============================================================================
---
forrest/trunk/plugins/org.apache.forrest.plugin.output.pdf/src/documentation/content/xdocs/index.xml
(original)
+++
forrest/trunk/plugins/org.apache.forrest.plugin.output.pdf/src/documentation/content/xdocs/index.xml
Tue Sep 2 06:08:27 2008
@@ -24,10 +24,11 @@
<section>
<title>Apache Forrest - org.apache.forrest.plugin.output.pdf
Plugin</title>
<p>
- This plugin enables any Forrest page to be output as a PDF document.
+ This plugin (hereafter just called the PDF plugin) enables any
+ Forrest page to be output as a PDF document.
</p>
<p>
- To use it simply request a page with the <code>pdf</code> extension
+ To use it simply request a page with the <code>pdf</code> extension.
</p>
<note>
By default this plugin is included in a new Forrest project. You will
@@ -35,5 +36,150 @@
page, this will, of course, link to the PDF version of that page.
</note>
</section>
+
+ <section>
+ <title>Configuration options</title>
+
+ <p>The PDF plugin can be configured in several ways:</p>
+
+ <ul>
+ <li>font family configuration</li>
+
+ <li>other presentation changes: page size, copyright notes, etc.</li>
+
+ <li>i18n configuarion, which is actually two subtopics:<ul>
+ <li>font family configuration</li>
+
+ <li>l10n of label text</li>
+ </ul></li>
+ </ul>
+
+ <p>Each of these points will be covered in separate sections below.</p>
+ </section>
+
+ <section>
+ <title>Font Family Configuration</title>
+
+ <p>The font family can be specifed in different steps of granularity. As
+ of version 0.4 of the PDF plugin, all of the configuration can be done
+ on a per project basis. There is no need to touch the plugin itself, as
+ it used to be.</p>
+
+ <section>
+ <title>Preparations</title>
+
+ <p>If you want to change the actual font family, not only where to use
+ the generic <code>serif</code>, <code>sans-serif</code> and
+ <code>monospace</code> families, then you also need to take these
+ preparatory steps:</p>
+
+ <ol>
+ <li>Follow the instructions at <a
+
href="http://cocoon.apache.org/2.1/userdocs/pdf-serializer.html";>http://cocoon.apache.org/2.1/userdocs/pdf-serializer.html</a>
+ to create a font configuration file and font metrics files at
+ <code>$PROJECT_HOME/src/documentation/resources/fonts</code> (you
+ may have to create the <code>fonts</code> folder).</li>
+
+ <li>Specify the absolute path to the font configuration file you
+ created in step 1 as the value of the entity
+ <code>&pdf-config-file;</code> in the project entity file. The
+ file is located at:
+
<code>$PROJECT_HOME/src/documentation/resources/schema/symbols-project-v10.ent</code>.
+ The result should look something like:<source><!ENTITY
pdf-config-file
"/Users/foo/forrestproject/src/documentation/resources/fonts/config.xml"></source>(the
+ above would work for a user named <code>foo</code> on a typical
+ MacOS X system - adapt to your local OS as needed, but the path
+ needs to be absolute)</li>
+
+ <li>Finally, add the necessary configuration options to your
+ <code>forrest.properties.xml</code> file, as described below.</li>
+ </ol>
+ </section>
+
+ <section>
+ <title>Font family overrides/specifications</title>
+
+ <p>For the easiest type of changing the font family, add the following
+ lines to your <code>forrest.properties.xml</code> file:</p>
+
+ <source> <property name="output.pdf.fontFamily.serif"
value="serif"/>
+ <property name="output.pdf.fontFamily.sansSerif" value="sans-serif"/>
+ <property name="output.pdf.fontFamily.monospace"
value="monospace"/></source>
+
+ <p>and replace the default values above with your preferred font
+ family, e.g. <code>DejaVuSans</code>, etc. Using these properties, you
+ will change the font family of whole classes of text types at once. If
+ you need proper i18n support for your language (more below) in the pdf
+ files, this is usually the easiest way to go - just replace the
+ generic families with your chosen font families.</p>
+
+ <p>If you need to override or specify the font family for a certain
+ text type, add one or more of the following properties to your
+ <code>forrest.properties.xml</code> file:</p>
+
+ <source> <property name="output.pdf.fontFamily.rootFontFamily"
value="serif" />
+ <property name="output.pdf.fontFamily.headerFooterFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.documentTitleFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.versionFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.authorsFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.TOCTitleFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.sectionTitleFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.sourceFontFamily"
value="monospace" />
+ <property name="output.pdf.fontFamily.codeFontFamily"
value="monospace" />
+ <property name="output.pdf.fontFamily.warningTitleFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.noteTitleFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.fixmeTitleFontFamily"
value="sans-serif" /></source>
+
+ <p>The given values are defaults, and should be replaced with what you
+ want. If you want, you can further specify the font family for
+ variants of the
+ <code>output.pdf.fontFamily.headerFooterFontFamily</code> property
+ using the following properties instead:</p>
+
+ <source> <property
name="output.pdf.fontFamily.firstFooterFontFamily" value="sans-serif" />
+ <property name="output.pdf.fontFamily.evenHeaderFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.evenFooterFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.oddHeaderFontFamily"
value="sans-serif" />
+ <property name="output.pdf.fontFamily.oddFooterFontFamily"
value="sans-serif" /></source>
+
+ <p>It is possible to do further customisations of the pdf rendering by
+ editing the stylesheets found in ...</p>
+ </section>
+ </section>
+
+ <section>
+ <title>Other presentation options</title>
+
+ <p>
+ Presentation changes like page size, copyright notes, etc. are
presently
+ specified in the <code>skinconfig.xml</code> file. See separate
documentation for
+ further info.
+ </p>
+ </section>
+
+ <section>
+ <title>I18n Configuration</title>
+
+ <section>
+ <title>Font Family Configuration</title>
+
+ <p>For some languages, the default font families (<code>serif</code>,
+ <code>sans-serif</code>, <code>monospace</code>) do not render all
+ characters, giving squares, question marks or nothing instead in the
+ rendered pdf document. This is known to be an issue with CJK
+ languages, as well as with lesser used languages such as Sámi. If this
+ is the case for your language(s), please follow the steps above to
+ configure the pdf plugin to use a font family known to contain all
+ characters needed. For many alphabetic languages, the free and open
+ source <a
+ href="http://dejavu.sourceforge.net/wiki/index.php/Main_Page";>DejaVu
+ font family</a> nowadays has quite good coverage.</p>
+ </section>
+
+ <section>
+ <title>L10n of label text</title>
+
+ <p>[TO BE WRITTEN]</p>
+ </section>
+ </section>
</body>
-</document>
+</document>
\ No newline at end of file
