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 @@
Apache Forrest - org.apache.forrest.plugin.output.pdf Plugin

- 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.

- To use it simply request a page with the pdf extension + To use it simply request a page with the pdf extension.

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.
+ +
+ Configuration options + +

The PDF plugin can be configured in several ways:

+ + + +

Each of these points will be covered in separate sections below.

+
+ +
+ Font Family Configuration + +

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.

+ +
+ Preparations + +

If you want to change the actual font family, not only where to use + the generic serif, sans-serif and + monospace families, then you also need to take these + preparatory steps:

+ +
    +
  1. Follow the instructions at http://cocoon.apache.org/2.1/userdocs/pdf-serializer.html + to create a font configuration file and font metrics files at + $PROJECT_HOME/src/documentation/resources/fonts (you + may have to create the fonts folder).
    2. + +
  2. Specify the absolute path to the font configuration file you + created in step 1 as the value of the entity + &pdf-config-file; in the project entity file. The + file is located at: + $PROJECT_HOME/src/documentation/resources/schema/symbols-project-v10.ent. + The result should look something like:<!ENTITY pdf-config-file "/Users/foo/forrestproject/src/documentation/resources/fonts/config.xml">(the + above would work for a user named foo on a typical + MacOS X system - adapt to your local OS as needed, but the path + needs to be absolute)
    3. + +
  3. Finally, add the necessary configuration options to your + forrest.properties.xml file, as described below.
    4. +
+
+ +
+ Font family overrides/specifications + +

For the easiest type of changing the font family, add the following + lines to your forrest.properties.xml file:

+ + <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"/> + +

and replace the default values above with your preferred font + family, e.g. DejaVuSans, 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.

+ +

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 + forrest.properties.xml file:

+ + <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" /> + +

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 + output.pdf.fontFamily.headerFooterFontFamily property + using the following properties instead:

+ + <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" /> + +

It is possible to do further customisations of the pdf rendering by + editing the stylesheets found in ...

+
+
+ +
+ Other presentation options + +

+ Presentation changes like page size, copyright notes, etc. are presently + specified in the skinconfig.xml file. See separate documentation for + further info. +

+
+ +
+ I18n Configuration + +
+ Font Family Configuration + +

For some languages, the default font families (serif, + sans-serif, monospace) 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 DejaVu + font family nowadays has quite good coverage.

+
+ +
+ L10n of label text + +

[TO BE WRITTEN]

+
+
- + \ No newline at end of file