Task export-pdf
This task can be used to convert a portable or processed PSML document to PDF according to rules in the PDF export config usage.
To use this Ant extension standalone outside PageSeeder you can download the pso-pdf-ant-x.jar and pso-pdf-core-x.jar files from maven central .
Definition
Minimal definition:
<export-pdf src="[source]" />
Full definition:
<export-pdf src="[source]"
dest="[destination]"
fontfolder="[font base folder]"
fontconfig="[font config file]"
working="[working folder]"
debug="true|false">
<config file="[config file]"
priority="[priority number]"/>
</export-pdf>
Attributes
| Attribute | Description | Required |
|---|---|---|
| src | Path to the .psml source file to process | Yes |
| dest | Path to the destination file. If unspecified, the default value is the name and location of the source with .pdf extension | No |
| fontfolder | Path to the font base folder | No |
| fontconfig | Path to the font config XML file | No |
| working |
The directory holding temporary files such as the concatenated configs files and XSL-FO scripts. The default is: [java.io.tmpdir]/antpdf-[number] | No |
| debug | If true an fo.xml file is created under the working folder | No |
Elements
<config>
Defines a config file which overrides rules in the default config file. There might be multiple <config> elements.
| Attribute | Description | Required | Default |
|---|---|---|---|
| file | Path to a configuration file | Yes | |
| name | Use default to apply the rules to all, or else specify the name of a PSML document type. DEPRECATED use document labels for custom styles. | No | default |
| priority | The priority number for the rules in this config file. When there are multiple files, higher priority overrides lower. | No | 1 |
<configs>
This element is deprecated, use <config> instead.
Defines a set of config files which overrides rules in the default config file. There might be multiple <configs> elements. Any config files with the following path is read [config folder]/[document type]/pdf-export-config.xml
| Attribute | Description | Required | Default |
|---|---|---|---|
| folder | Path to a configuration folder | Yes | |
| priority | The priority number for the rules in these config files. When there are multiple files, higher priority overrides lower. | No | 1 |
Custom fonts
Custom fonts require pso-pdf v0.4.15 or higher.
The PDF specification says that the following fonts or equivalents must be available in every PDF reader: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats.
However, these only cover a subset of characters. The export-pdf/@fontfolder and export-pdf/@fontconfig optional attributes can be used to configure custom fonts to embed in the PDF for additional characters or layout requirements.
The @fontconfig must be a path (relative to the build.xml or absolute) to an XML config file. Following is the XML file used by the default PageSeeder PDF export, where @embed-url is the path to each font file, relative to @fontfolder. The <font-triplet> elements specify how that is referenced in the PDF export configuration.
<fonts>
<font embed-url="NotoSans-Regular.ttf">
<font-triplet name="NotoSans" style="normal" weight="normal"/>
</font>
<font embed-url="NotoSans-Bold.ttf">
<font-triplet name="NotoSans" style="normal" weight="bold"/>
</font>
<font embed-url="NotoSans-Italic.ttf">
<font-triplet name="NotoSans" style="italic" weight="normal"/>
</font>
<font embed-url="NotoSans-BoldItalic.ttf">
<font-triplet name="NotoSans" style="italic" weight="bold"/>
</font>
<font embed-url="NotoSansMath-Regular.ttf">
<font-triplet name="NotoSansMath" style="normal" weight="normal"/>
<font-triplet name="NotoSansMath" style="normal" weight="bold"/>
<font-triplet name="NotoSansMath" style="italic" weight="normal"/>
<font-triplet name="NotoSansMath" style="italic" weight="bold"/>
</font>
</fonts>
The default PDF export configuration references these fonts as follows. The ZapfDingbats font is included for the tick/check mark character.
<property name="font-family"
value="NotoSans,NotoSansMath,sans-serif,ZapfDingbats"/>
Usage
Invoking in Ant
This task is included by default in the PageSeeder publisher so <taskdef/> is only required when using it outside the publisher.
<project ... xmlns:psp="antlib:org.pageseeder.pdf.ant">
<!-- only required for standalone -->
<taskdef uri="antlib:org.pageseeder.pdf.ant"
resource="org/pageseeder/pdf/ant/antlib.xml"
classpath="pso-pdf-ant-0.2.2.jar"/>
<target ... >
<!-- Invoke Task -->
<psp:export-pdf src="test.psml" dest="result.pdf"/>
</target>
</project>
Using a namespace is not required, but it is a good mechanism to know the origin of the task. The recommended namespace is psp. The following is an example of custom fonts being used.
<psp:export-pdf src="test.psml"
dest="result.pdf"
fontfolder="fonts"
fontconfig="fonts/font-config.xml"/>
Standalone
Because it is designed to work as a standalone process, no connection to PageSeeder is required. However, when run in the context of a PageSeeder export, use the Task export and Task process to download the source PSML file.
How does it work?
This Ant task:
Loads the config files.
Creates XSL-FO according to the rules in the config files and the default config.
Uses Apache FOP to generate the PDF output from the XSL-FO.