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 portPrimarySequenceContent typesDefault binding
source  xml html 
stylesheet ✔ text p:empty
Output portPrimarySequenceContent typesDefault binding
result✔  any 
Option nameTypeDefault value
content-typexs:string?()
parametersmap(xs:QName,item()*)?()
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
  |   <p:input port="source" 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
CodeDescription
err:XC0166It is a dynamic error (err:XC0166) if the requested document cannot be produced.
err:XC0204It is a dynamic error (err:XC0204) if the requested content-type is not supported.
err:XD0079It 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

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 URIProcessor selected
https://xmlcalabash.com/paged-media/css-formatter/antenna-houseAntenna House
https://xmlcalabash.com/paged-media/css-formatter/princePrince XML
https://xmlcalabash.com/paged-media/css-formatter/weasyprintWeasyprint
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 nameType
EmbedAllFontsExstring: “part”, “base14”, or “all”
ExitLevelinteger
ImageCompressioninteger
NoAccessibilityboolean
NoAddingOrChangingCommentsboolean
NoAssembleDocboolean
NoChangingboolean
NoContentCopyingboolean
NoFillFormboolean
NoPrintingboolean
OptionFileURIstring
OwnersPasswordstring
TwoPassFormattingboolean

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

The following content-types are supported:

Content typeAH 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.3.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 nameType
allowAnnotateboolean
allowAssemblyboolean
allowCopyboolean
allowCopyForAccessibilityboolean
allowModifyboolean
allowPrintboolean
artificialFontsboolean
attachmentslist of string
authMethodsbasic”, “digest”, “ntlm”, or “negotiate
authPasswordstring
authPreemptiveboolean
authSchemehttp” or “https
authServerstring
authUserstring
authorStyleboolean
baseURLstring
compressboolean
convertColorsboolean
cookieJarstring
cookieslist of string
debugboolean
defaultStyleboolean
embedFontsboolean
encryptboolean
exePathstring
failDroppedContentboolean
failInvalidLicenseboolean
failMissingGlyphsboolean
failMissingResourcesboolean
failPdfProfileErrorboolean
failPdfTagErrorboolean
failSafeboolean
failStrippedTransparencyboolean
fallbackCmykProfilestring
forceIdentityEncodingboolean
httpProxystring
httpTimeoutstring
iframesboolean
inputTypeauto”, “html”, or “xml
javascriptboolean
keyBits40 or 128
licenseFilestring
licenseKeystring
logstring
maxPassesstring
mediastring
networkboolean
objectStreamsboolean
ownerPasswordstring
parallelDownloadsboolean
pdfAuthorstring
pdfCreatorstring
pdfEventScriptslist of string pairs
pdfFormsboolean
pdfIdstring
pdfKeywordsstring
pdfLangstring
pdfOutputIntentstring
pdfProfilePDF/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”.
pdfScriptstring
pdfSubjectstring
pdfTitlestring
redirectsboolean
scriptsstring
sslCaCertstring
sslCaPathstring
sslCertstring
sslCertTypepem” or “der
sslKeystring
sslKeyPasswordstring
sslKeyTypepem” or “der
sslVerificationdefault”, “tlsv1”, “tlsv1.0”, “tlsv1.1”, “tlsv1.2”, or “tlsv1.3
sslVersionstring
subsetFontsboolean
taggedPdfboolean
userPasswordstring
verboseboolean
warnCssUnknownboolean
warnCssUnsupportedboolean
xincludeboolean
xmlExternalEntitiesboolean
xmpstring

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 nameType
exePathstring
mediaTypestring
baseUrlstring
attachmentstring
pdfIdentifierstring
pdfVariantstring
pdfVersionstring
pdfFormsboolean
uncompressedPdfboolean
customMetadataboolean
presentationalHintsboolean
optimizeImagesboolean
jpegQualitystring
fullFontsboolean
hintingboolean
cacheFolderstring
dpistring
verboseboolean
debugboolean
quietboolean
timeoutstring

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.