p:css-formatter

Name

p:css-formatter — The standard p:css-formatter step.

Synopsis

The p:css-formatter step applies CSS formatting to an XML or HTML document. The output of this step is often, but not necessarily, a PDF document.

Input port	Primary	Sequence	Content types	Default binding
source	✔		xml html
stylesheet		✔	text	p:empty

Output port	Primary	Sequence	Content types	Default binding
result	✔		any

Option name	Type	Default value
content-type	xs:string?	()
parameters	map(xs:QName,item()*)?	()

Declaration

1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
  |   <p:input port="source" primary="true" content-types="xml html"/>
  |   <p:input port="stylesheet" content-types="text" sequence="true">
  |      <p:empty/>
5 |   </p:input>
  |   <p:output port="result" content-types="any"/>
  |   <p:option name="parameters" as="map(xs:QName,item()*)?"/>
  |   <p:option name="content-type" as="xs:string?"/>
  |</p:declare-step>

Errors

Code	Description
`err:XC0166`	It is a dynamic error (`err:XC0166`) if the requested document cannot be produced.
`err:XC0204`	It is a dynamic error (`err:XC0204`) if the requested content-type is not supported.
`err:XD0079`	It is a dynamic error (`err:XD0079`) if a supplied content-type is not a valid media type of the form “`type/subtype+ext`” or “`type/subtype`”.

Implementation defined features

The use of media type parameters on the content-type option is implementation-defined.
If the content-type option is not specified, the output type is implementation-defined.
The precise way that the p:css-formatter step selects stylesheets is implementation-defined.
A formatter may take any number of optional rendering parameters via the step's parameters; such parameters are defined by the CSS implementation used and are implementation-defined.
The CSS level and the particular CSS features supported by p:css-formatter are implementation-defined.

Description

The p:css-formatter step is a standard XProc 3.1 step. It is also described on XProcRef.org.

XML Calabash supports several CSS formatter implementations. There is also a service provider interface so that additional implementations can be provided by third parties. Several XSL formatters are also supported.

Processors can be selected in the configuration file with the cc:paged-media element as described in the User Guide.

Configuration URI	Processor selected
`https://xmlcalabash.com/paged-media/css-formatter/antenna-house`	Antenna House
`https://xmlcalabash.com/paged-media/css-formatter/prince`	Prince XML
`https://xmlcalabash.com/paged-media/css-formatter/weasyprint`	Weasyprint
`https://xmlcalabash.com/paged-media/css-formatter/pagedjs`	Paged.js

☝

Important

You must also obtain and install the relevant processor, configure it on your system, and satisfy its licensing requirements. XML Calabash doesn’t ship with the processors themselves.

Antenna House

In order to use the Antenna House formatter, you must install and configure Antenna House Formatter.

You can configure the formatter with a configuration property or via the parameters option. The following configuration options are supported:

Property name	Type
`EmbedAllFontsEx`	string: “part”, “base14”, or “all”
`ExitLevel`	integer
`ImageCompression`	integer
`NoAccessibility`	boolean
`NoAddingOrChangingComments`	boolean
`NoAssembleDoc`	boolean
`NoChanging`	boolean
`NoContentCopying`	boolean
`NoFillForm`	boolean
`NoPrinting`	boolean
`OptionFileURI`	string
`OwnersPassword`	string
`TwoPassFormatting`	boolean

For more information about these properties, consult the AH Formatter API documentation.

The following content-types are supported:

Content type	AH output format
`application/pdf`	`@PDF`
`application/postscript`	`@PS`
`application/vnd.inx`	`@INX`
`application/vnd.mif`	`@MIF`
`image/svg+xml`	`@SVG`
`text/plain`	`@TEXT`

PrinceXML

In order to use the PrinceXML formatter, you must install and configure Prince.

☝

Backwards incompatible change

In beta7, XML Calabash switched to the Prince java wrapper version 1.5.0. This added many options, changed the names of several options, and removed a few.

You can configure the formatter with a configuration property or via the parameters option. The configuration options listed in the table below are supported.

ⓘ

Note

The underlying Prince API has “negative options”, but for consistency, all of the options on this step are positive. (To disable parallel downloads, set parallelDownloads to false, rather than setting noParallelDownloads to true).

Property name	Type
`allowAnnotate`	boolean
`allowAssembly`	boolean
`allowCopy`	boolean
`allowCopyForAccessibility`	boolean
`allowModify`	boolean
`allowPrint`	boolean
`artificialFonts`	boolean
`attachments`	list of string
`authMethods`	“`basic`”, “`digest`”, “`ntlm`”, or “`negotiate`”
`authPassword`	string
`authPreemptive`	boolean
`authScheme`	“`http`” or “`https`”
`authServer`	string
`authUser`	string
`authorStyle`	boolean
`baseURL`	string
`compress`	boolean
`convertColors`	boolean
`cookieJar`	string
`cookies`	list of string
`debug`	boolean
`defaultStyle`	boolean
`embedFonts`	boolean
`encrypt`	boolean
`exePath`	string
`failDroppedContent`	boolean
`failInvalidLicense`	boolean
`failMissingGlyphs`	boolean
`failMissingResources`	boolean
`failPdfProfileError`	boolean
`failPdfTagError`	boolean
`failSafe`	boolean
`failStrippedTransparency`	boolean
`fallbackCmykProfile`	string
`forceIdentityEncoding`	boolean
`httpProxy`	string
`httpTimeout`	string
`iframes`	boolean
`inputType`	“`auto`”, “`html`”, or “`xml`”
`javascript`	boolean
`keyBits`	40 or 128
`licenseFile`	string
`licenseKey`	string
`log`	string
`maxPasses`	string
`media`	string
`network`	boolean
`objectStreams`	boolean
`ownerPassword`	string
`parallelDownloads`	boolean
`pdfAuthor`	string
`pdfCreator`	string
`pdfEventScripts`	list of string pairs
`pdfForms`	boolean
`pdfId`	string
`pdfKeywords`	string
`pdfLang`	string
`pdfOutputIntent`	string
`pdfProfile`	“`PDF/A-1a`”, “`PDF/A-1a+PDF/UA-1`”, “`PDF/A-1b`”, “`PDF/A-2a`”, “`PDF/A-2a+PDF/UA-1`”, “`PDF/A-2b`”, “`PDF/A-3a`”, “`PDF/A-3a+PDF/UA-1`”, “`PDF/A-3b`”, “`PDF/UA-1`”, “`PDF/X-1a:2001`”, “`PDF/X-1a:2003`”, “`PDF/X-3:2002`”, “`PDF/X-3:2003`”, or “`PDF/X-4`”.
`pdfScript`	string
`pdfSubject`	string
`pdfTitle`	string
`redirects`	boolean
`scripts`	string
`sslCaCert`	string
`sslCaPath`	string
`sslCert`	string
`sslCertType`	“`pem`” or “`der`”
`sslKey`	string
`sslKeyPassword`	string
`sslKeyType`	“`pem`” or “`der`”
`sslVerification`	“`default`”, “`tlsv1`”, “`tlsv1.0`”, “`tlsv1.1`”, “`tlsv1.2`”, or “`tlsv1.3`”
`sslVersion`	string
`subsetFonts`	boolean
`taggedPdf`	boolean
`userPassword`	string
`verbose`	boolean
`warnCssUnknown`	boolean
`warnCssUnsupported`	boolean
`xinclude`	boolean
`xmlExternalEntities`	boolean
`xmp`	string

Properties with the type “list of string” means a single string with space separated values.

The pdfEventScripts property is also a single string with space separated values. After splitting the string, it must consist of a sequence of pairs where the first item is the event type (“will-close”, “will-save”, “did-save”, “will-print”, “did-print”) and the second item is the script filename.

(This business of using single strings and splitting them on white space is a bit of a mess. It’s motivated in part by the fact that the default values for the properties come from attribute values in the configuration file. If it’s problematic, please open an issue.)

The exePath property is used to locate the prince executable. If it’s not specified, XML Calabash will first look for the system property com.xmlcalabash.css.prince.exepath, and if that doesn’t exist, it will search the user’s PATH environment variable.

For more information about the properties, consult the Prince API documentation.

Weasyprint

In order to use the Weasyprint formatter, you must install and configure WeasyPrint.

You can configure the formatter with a configuration property or via the parameters option. The following configuration options are supported:

Property name	Type
`exePath`	string
`mediaType`	string
`baseUrl`	string
`attachment`	string
`pdfIdentifier`	string
`pdfVariant`	string
`pdfVersion`	string
`pdfForms`	boolean
`uncompressedPdf`	boolean
`customMetadata`	boolean
`presentationalHints`	boolean
`optimizeImages`	boolean
`jpegQuality`	string
`fullFonts`	boolean
`hinting`	boolean
`cacheFolder`	string
`dpi`	string
`verbose`	boolean
`debug`	boolean
`quiet`	boolean
`timeout`	string

The exePath property is used to locate the weasyprint executable. If it’s not specified, XML Calabash will first look for the system property com.xmlcalabash.css.weasyprint.exepath, and if that doesn’t exist, it will search the user’s PATH environment variable.

For more information about the properties, consult the WeasyPrint documentation.

Paged.js

In order to use the Paged.js formatter, you must install and configure paged.js and the pagedjs-cli processor. You will also need to have Google Chrome installed, I believe, as that’s the processor that Paged.js drives.

You can configure the formatter with a configuration property or via the parameters option. The following configuration options are supported (based on the command-line options of pagedjs-cli version 0.4.3):

Property name	Type
`exePath`	string
`additionalScript`	list of string
`allowedDomain`	list of string
`allowedPath`	list of string
`blockLocal`	boolean
`blockRemote`	boolean
`browserArgs`	string
`browserEndpoint`	string
`debug`	boolean
`extra-header`	list of string
`forceTransparentBackground`	boolean
`height`	string
`html`	boolean
`landscape`	boolean
`media`	string
`outline-tags`	string
`page-size`	string
`style`	list of string
`timeout`	string
`warn`	boolean
`width`	string

ⓘ

Note

The “list of string” properties must be configured with a single space-delimited value. In other words the value “a b c” will be processed as a list of three values: “a”, “b”, and “c”.

The exePath property is used to locate the weasyprint executable. If it’s not specified, XML Calabash will first look for the system property com.xmlcalabash.css.pagedjs.exepath, and if that doesn’t exist, it will search the user’s PATH environment variable.

For more information about the properties, consult the Paged.js documentation.

Prev	Up	Next
p:count	Home	p:delete