BFO Publisher

While it is completely possible to use BFO Publisher to parse HTML without any additional namespaces, some additional features require them. In particular the <xi:include> syntax to include external files requires the appropriate namespace to be defined. So BFO Publisher lets you extend the list of namespaces known to HTML with an extension

The bfo-ext-html-namespace environment variable can be set to configure how namespaces are derived from HTML input. The values are:

Once mapped, the additional namespaces can be used in HTML. For example, to use the XInclude syntax:

or, using the namespace mapping

Note the use of closing tags is required - although we can customize the namespaces in HTML, we cannot customize the parsing process. Self-closing tags are not part of the HTML syntax, and as the HTML parse is tolerant of unclosed tags a failure to close any custom element like this will result in incorrect output.

Almost every configuration that can be applied to a file conversion in BFO Publisher can be configured by setting the appropriate environment variables. Throughout this documentation they’ll be listed just like the two above, in box with "Environment Variable" at the top (for example, bfo-pdf-profile).

Like other at-rules in CSS, they are processed in the normal CSS priority: rules in user stylesheets will override author stylesheets, which will override user-agent stylesheets, and if two rules have the same hierarchy, a later value will override an earlier one.

Most importantly, environment variables only apply going forward. They will not be applied to any rules already parsed - they’re the CSS equivalent of global constants, so they should be set as near the top of the document as possible. This mostly matters when environment variables are used in Media Queries, see that section for details on how this is done.

PDF has a number of predefined profiles which impose restrictions on the format in the name of compatibility. Broadly they are:

They all overlap to a degree - it is possible to create a PDF that is compliant with all three. PDF/A and PDF/X need to be self-describing, so all fonts and colorspaces are embedded, and PDF/UA requires the PDF to be tagged, and places restrictions on the HTML input - for example, images need an alt attribute, tables must be correctly formed with headers etc.

Choosing the profile simply involves setting an environment variable, either externally or from within the document by way of CSS or <meta> tags.

More than one Profile Name from the following list can be specified, although they must not be incompatible (it cannot be both PDF/A-2 and PDF/A-3, for example). The values are compared lower case and ignoring anything other than letters or digits, so you don’t have to worry about punctuation.

HTML and XML documents are structured using tags, but PDF is primarily a page description language so in general has no need for structure. But when consuming a PDF with some form of accessibility technology, such as a screen reader, braille display, or simply removing a background behind text for readabilty, having an XML-like tag structure is crucial.

These accessibilty technologies are commonly abbreviated as "AT", and a PDF with this structure is called a Tagged PDF.

PDF/UA (ISO14289) is a particular profile of Tagged PDF designed to work with AT by placing a number of requirements on on how the tags are used. The current version is PDF/UA-1 and targets PDF 1.7, so it’s commonly (but not necessarily) combined with PDF/A-2a and PDF/A-3a. PDF/UA-2 will apply to PDF 2.0 and PDF/A-4, but is under development.

Generating a PDF/UA document does not require an in depth knowledge of PDF tags, but it does mean ensuring the source document is created in a certain way. Many of the rules are the same as for HTML documents conforming to WCAG. They’re listed here:

A mapping from a <td> to <th> ensures that every non-header cell in table has a header describing it. For simple tables, say where the first row or first column is entirely <th> elements, this can be derived automatically but for more complex tables this may need to be specified explicitly. As with WCAG, this can be done in one of two ways:

So long as one of these techniques can be used to map every <td> in a table to a corresponding <th>, this condition will be met for PDF/UA.

To enable PDF/UA output, use the bfo-pdf-profile tag described in the previous section

or use one of the other methods of setting this property

Even without the relatively strict requirements of PDF/UA, Tagged PDF is useful for many PDF consumers.

While there is a slight cost in terms of file-size and performance, BFO recommend that tags are always enabled unless you’re certain that the generated PDF will never be accessed by anyone using accessibility tools.

Selecting a tagged profile like PDF/A-2a, PDF/A-3a or PDF/UA-1 will turn on tags automatically, but they can easily be turned them on manually:

Tagged output will use standard tag mappings from HTML, SVG and MathML. One significant different between PDF 1.x and PDF 2.x is that PDF 2 allows namespaces on the tags. BFO Publisher makes full use of this, and if namespaces are allowed it should be possible to mostly reconsitute the original HTML structure from the PDF.

Tagged PDF version 2.0 allows a Pronunciation Lexicon to be stored in the PDF and phonemes to be associated with a PDF tag. When generating a Tagged PDF 2.0 file, the data-ssml-phoneme-ph and data-ssml-phoneme-alphabet attributes defined in https://www.w3.org/TR/spoken-html/#data-ssml-phoneme will be used if specified (the shorthand data-ssml attribute is also supported).

Best practice for pronunciation hints on the internet is far from decided; SSML, ePub and PDF all have enough in common to make implementing support fairly simple, even though the SSML specification is currently a working draft and so liable to change. Fow now, here’s an example showing the current state.

It’s possible to attach files to a PDF being generated by using a special <link> annotation. Some examples:

If the href attribute is a fragment URL, the element it refers to be will be attached to the PDF as an XML document unless the element is a <style> element (in which case the type will be text/css, and only the content of the element will be attached) or a <script> element (in which case the type will be the value of the script’s type attribute, or text/javascript if unspecified, and only the content of the element will be attached). Fragment URL processing is new in version 1.3.

Finally, if the href attribute is # and the type attribute is text/css, all the stylesheets referenced by the document will be attached to the PDF. Special processing occurs here to ensure @import rules are expanded, CSS is converted to UTF-8, URLs are made absolute, and other steps which allow the CSS to be extracted from the PDF and usefully used where required, as as when deriving HTML from PDF. This functionaliy is new in version 1.3.

The generated PDF can be password encrypted, or encrypted with public keys for specific recipients (although this has limited support in PDF viewers). As usual this is controled by environment properties.

For standard password encryption the following properties apply.

Here’s an example showing a fairly typical use case for password encryption - the PDF can be opened by anyone with the password password, and once opened it can’t be printed:

Public key encryption uses a similar set of properties, but instead of bfo-pdf-encrypt-password and bfo-pdf-encrypt-admin-password there is bfo-pdf-encrypt-recipient.

Each recipient has the print, change and extract rights set at the time the recipient is added - there may be more than one recipient, each with different access rights. The public key is an X.509 certificate which, as with Digital Signatures, can be a KeyStore (the URL may contain fragment parameters to select the key) or a PEM encoded X.509 certificate.

Here’s the above example, changed from password encryption to use a single public key for encryption. Anyone with this key will be able to open the PDF, but won’t be able to print it.

A more complex example allows two students to view the PDF and make no changes, and one teacher who may edit the form and annotate it. To change things up, let’s assume all the X.509 certificates are in a single file - maybe a Java KeyStore or be a single text file with multiple PEM encoded certificates, it doesn’t matter. We’ll use the cn fragment parameter to choose which entry in the key store we want, just as we can do for Digital Signatures

The remaining PDF specific environment variables set general PDF Options - this covers aspects like whether the PDF opens with the bookmarks window or the thumbnail window, whether it opens up in single page or one column mode, and so on.

Please consult the API method listed above for the full list. Here’s an example showing how to select the thumbnail panel when the PDF is opened, and display the pages as one long column.

While PDF is usually a static document, the format does have some support for layers. We’re using this term to group two different concepts in PDF - annotations, which sit above the page and are largely independent, and optional content layers which are part of the page, but can be selectively turned on or off.

By default no layers are created, but an element can be assigned to a layer with -bfo-layer-type and various other -bfo-layer-nnn properties used to configure the layer.

Any <script> elements in the input document normally define scripts to run immediately; they’re applied to the document itself. However the PDF format also supports JavaScript, which runs under a completely different environment: there is no DOM, for example, and instead of dealing with elements there are structures representing pages, form fields and other PDF constructs.

Currently BFO Publisher does not support JavaScript which is run on the input document, but scripts which are intended for embedding in the PDF are very much supported. To mark a script as destined for the PDF, set the type attribute to the value bfo/pdfscript

The use of a custom Media Type will also prevent this content from being processed if the document is loaded in a web-browser.

BFO Publisher supports some custom hyperlink formats which allow <a> elements to perform actions within the PDF viewer - although support for these depends on the viewing environment. Actions such as goto() or FirstPage are fairly widely supported, but many others will require Adobe Acrobat or a PDF Viewer of a similar level of suport.

Probably the most common use will be to print, for example <a href="pdf:Print">Print this file</a>

For example, to play an audio clip embedded in the PDF with the legacy annotation type:

Bookmarks (also called Outlines in PDF) are a semi-standard part of CSS defined in css-gcpm-3.

The canonical examples of CSS bookmarks from the specification tend to look like this:

which presupposes that the depth of each heading is known in advance; the choice of <h1>, <h2> etc. define the depths. BFO Publisher adds the copy and increment values for when the depth is not known and the document is structured with nesting. The example below will have the same bookmark levels as the example above.

Encapsulation describes the strategy used to handle URLs in the SVG output. As a purely Web format, SVG allows specifying arbitrary URLs for links to the resources contained in the document, notably external bitmap images. Arbitrary URLs may also have been specified in the source XML and CSS to load content resources from. However, we usually want the resulting document to be self-contained and not to depend on external content defined elsewhere on the Web, where it may be changed, moved or deleted, or become unavailable due to network failure.

The simplest strategy to overcome this problem is simply to embed all external loaded resources into the target output SVG. For binary content such as bitmap images, this can be done using a data: URL.

The advantage of encapsulation is that the resulting SVG has no dependencies and will always look the same as the source document did at the time that it was processed by BFO Publisher. However, this comes at a cost. Images and other binary content must be Base64 encoded and embedded into the output file, which may result in very large files. Also, the data: URL strategy does not support defining some content once and referencing it in multiple separate places, so there is a potential for massive duplication of binary assets.

The encapsulation configuration parameter specifies the encapsulation strategy.

Pagination describes the strategy used to handle paged media in the SVG output.

The pagination configuration parameter specifies the pagination strategy.

The @page CSS at-rule specifies the overall page layout, including its size and margins. Other CSS properties can be specified, either for all paged content, or only for pages that match certain criteria. The @page rule is defined at https://www.w3.org/TR/css-page-3/#at-page-rule

Page selectors can specify a page identifier or page pseudo-classes. The following page selectors are defined:

Whether a page is left or right depends on the writing direction of the document. If the writing-direction is left-to-right the first page will match :right; if it has a writing direction of right-to-left it will match :left.

The page property forces the element to be on a page from the named page group, triggering a page break if necessary.

Named page groups allow the document to be broken up into sections, allowing different headers or footers to be applied to different sections of the document - for example, a cover page may have no page number, the introduction page numbers in lower-case roman, while the main body of the document uses arabic numerals. Here’s how you could do that:

This example resets the page counter to 1 to ensure the header and main sections of the PDF both start at one. The page property causes a new page group to begin, which forces a page break and allows the :nth(n of m) selector to be applied. For example, to select the second page of the body section you could use the selector :nth(2 of body).

Page margin boxes can be used within the @page rule to further subdivide the page into separate regions, such as headers and footers. These are all CSS at-rules with their own blocks. Conceptually, the page area is divided into nine boxes. The page content is displayed in the center (horizontally) and middle (vertically). The corner areas are then referred to as "corners", and the edge areas (above, below, and to either side of the content) are further subdivided into 3 boxes representing their start, central, and end areas.

The page margin box types are as follows:

The size property specifies the target size and orientation of the page box. It is only relevant inside an @page block. In PDF terminology it sets the trim box (unless the bleed property is negative, in which case it sets the bleed box).

The marks property determines whether printer marks are added to the page. With the bleed property, printer marks show the printer where to trim the output.

The bleed property specifies the extent of the page bleed area outside the page box defined by size. Bleed is typically set when the page contains backgrounds that are supposed to extend to the edge. Any solid, gradients, or tiled image backgrounds that extend to the edge of the area defined by size will be automatically extended into the bleed box.

When specified as a positive length it determines how far outward, in each direction, the bleed box extends past the page box. If specified as a negative length then the size property is assumed to specify the bleed box, and the bleed property defines the trim box with respect to that.

The default value of auto evaluates to 0 unless the page has crop marks (see the marks CSS property), in which case it’s 6pt.

The -bfo-trim property specifies the distance between the page box (i.e. the box defined by the size property) and the edge of the physical page, known as the media box in PDF. As with bleed, the default value of auto evaluates to 0 unless the page has crop marks, in which case it’s bleed + 6pt.

This property is a shorthand for the properties -bfo-trim-top, -bfo-trim-right, -bfo-trim-bottom, and -bfo-trim-left, which define the distances for each individual side in the same way as padding or margin.

It’s also possible to specify a value like -bfo-trim: to A4, which would set the four trim sizes to expand the page to a media box of A4, centering the content. This syntax is the word to followed by any value that would be valid for the size property (so to auto is valid).

A diagram may help to visualize this.

Here are some more example @page rules. Note the default page margin is 0, so if you’re setting any margin content, you should set margin too.

If you’d prefer to set the media box of the page directly and derive the trim box from that, that’s possible with some custom properties and calc() functions:

An important function of pagination is controlling where page breaking occurs. Page breaks are controlled via the following CSS properties:

The break-before, break-after, and break-inside property specifies how page breaks should occur before, after, and inside a box respectively.

Note that where page breaks occur is part of CSS fragmentation more generally; thus, some property values are agnostic as to whether they are page breaks or column breaks in multi-column output, whereas some are specifically relevant to page breaks.

Additionally, there are two properties that can be used to avoid breaking inside paragraphs that would result in too few lines in the paragraph before or after the break.

The orphans property specifies the minimum number of lines in a block container that must be shown at the bottom of the page. It must be a positive integer; the default value is 2.

The widows property specifies the minimum number of lines in a block container that must be shown at the top of the page. It must be a positive integer; the default value is 2.

BFO Publisher fully supports media queries as defined in https://www.w3.org/TR/mediaqueries-4/, plus a few useful extensions. The default media type is considered to be print to an A4 page size, but as all media properties can be overriden with environment variables this is easy to change. Pre-defined environment variables correspond to each non-derived media feature defined in https://www.w3.org/TR/mediaqueries-4/: width matches bfo-media-width, resolution matches bfo-media-resolution and so on. Most of these will never need changing, but some that will be are listed here.

CSS has a fairly sophisticated method of generating content - text which is inserted into the document but is not part of the input DOM. Typical uses are list counters, but any number of custom counters can be specified. BFO Publisher has full support for all types of generated content in the specification.

Unfortunately the specifications governing this are scatted: CSS Content 3, CSS Lists 3 (for counters) CSS Page 3 (for counters as the apply to pages) and CSS GCPM 3; although the latter is quite ancient, it has been used as a basis by most print layout engines.

Layout begins with the first page and ends with the last, which leads to a problem when using the pages counter, or the target-counter for an element that hasn’t yet been laid-out. How do we know what the value will be if it hasn’t been computed yet?

There are two approaches to work around this. First, we can allocate a fixed amount of space on the page for the counter, then come back and fill it in when the document is complete. Or, we can do a trial layout of the document to establish the value of the counter.

Which approach is controlled with the bfo-lookahead environment property

The default value is true, which means whenever a future value is required, the layout will continue until that value is known, then repeated with the correct value inserted into the DOM. This gives the best results but can require two passes - if the pages counter is used, we have to continue until the end of the document. BFO Publisher will avoid this where possible - for example, an entry in a table-of-contents preceded by a leader() does not require two passes, as the leader can be resized.

The alternative is to allocate a fixed block of space on the page for the number. This allows rendering to run in a single pass, which will be a significant win for documents with thousands of pages. The size of the gap is unlikely to be correct, but careful layout can minimise the effect of this - for example, ensuring there is no content to the right of a pages counter and that it’s left or center aligned on the page means the gap will not be noticed.

When including XML or HTML the content becomes part of the parent document so will inherit the styles from its container, and any styles defined in the included file will also apply globally. As this behaviour isn’t always desired, BFO Publisher defines a bfo:scope property to control this - while it can be used anywhere, it’s most useful with xi:include.

The values have the following meanings:

Here are some examples showing how this works. For clarity we’ve set bfo:scope on inline elements, which is perfectly valid, but we’d expect this to be mostly used on <xi:include>

In this example, the paragraph p1 has the bold style from the first stylesheet, and the italic style from the second stylesheet. When the div d1 closes, the bfo:scope="inherit" means the inner stylesheet is discarded, and paragraph p2 is no longer itaalic.

In this example, the paragraph p1 is only styled with the second stylesheet: the bfo:scope="isolate" prevents stylesheets defined outside the div d1 from applying within it. As with the previous example, the second stylesheet is discarded when d1 is closed.

Sometimes style rules should cross into isolated scopes - for example, when they define resources like fonts. The addition of bfo:scope="all" to the stylesheet at myfont.css will ensure that any rules it defines (such as @font-face) are applied even to isolated scopes.

The bfo:scope attribute can be set on any element. When set on <xi:include>, as with any namespace-qualified attribute it will be propagated to the root element (or elements, if appropriate) of the included resource.

Elements which set bfo:scope to isolate or inherit will match the :scope CSS selector (if no scope is declared, the :scope selector matches the root element). The :scope selector and the concept of a scoping root are standard CSS concepts, but the creation of a scope is not currently defined in CSS or HTML.

The output from any Template is assumed to be HTML by default; this is the case even if the data was originally loaded from an XML file. If the Template generates XML instead then this must be specified by adding a type="text/xml" attribute to the processing instruction. Our first example above would now look like this:

or when using the API

If the Template contains relative URLs to images or other resources, they will be resolved relative to the path of the Template file, not relative to the data file being parsed.

Environment variables beginning with freemarker. are passed to the FreeMarker configuration, minus the freemarker. prefix. For example, setting the Environment variable freemarker.incompatible_improvements to 2.3.27 would configure FreeMarker to use that version of its API. The bfo-lang environment variable, used to set the default language of the Report, is also used to set the FreeMarker default language.

FreeMarker supports recursion, so a malicious template could use all the available memory in Java. BFO Publisher will resolve the URL in the processing-instruction as normal, so in theory Templates could be loaded from any URL. To mitigate the security implications here, we’ve added a concept of a trusted resource. URLs with a scheme of file, jar or classpath are trusted, and so can contain a Templates. Attempting to load a Template from a non-trusted URL will fail. This is mostly of interest when using the web-service.

ZTemplate is a much simpler template language, and the only configurable is bfo-lang is used to set the default locale for templates, as with FreeMarker. ZTemplate is designed to prevent recursion and other types of runaway resource use, but for added security the trusted resource concept described for FreeMarker is also required for ZTempalte templates.

Template processing can run from the Web Service too, so long as the file being converted contains the required processing-instruction or one is specified in the processing_instructions property passed to convert (see [Conversion API in detail]). The Template must be a trusted URL, so to allow Templates to be uploaded to the service, BFO Publisher version 1.3 adds the trusted key to files added to the store. This key can only be set by a user with the admin/trusted grant (see Access Control).

The way we expect this to work is as follows.

Here’s the upload of the Template, as done by the admin user

And here’s the conversion - the data is uploaded as a file, so is sent as JSON serialized as a string (if sending CBOR, the data can also be application/cbor, serialized as a byte buffer). The template is referenced with a processing instruction as shown. The data is the same as the JSON example above.

Of course if the user doing the conversion has the admin/trusted grant, both the template and the datamodel can be uploaded in a single pass. Templates are cached and reused, and as BFO Publisher will identify them by their checksum it’s OK to upload them repeatedly if necessary - this will create extra network traffic, but not a lot of extra processing.

FreeMarker include and import are supported, as are includes in ZTemplate (they’re the same concept). Relative paths are resolved relative to the path of the Template file. Both are loaded using BFO Publisher resource loader, so are treated the same was as any other URL (see Security). As a rule of thumb, the URLs for these imported files should be relative in order to work without Security implications.

This is how most people think of metadata in HTML - the title and meta elements can be used to set the corresponding fields on the document. The vocabulary available with this approach is very limited however, so if you want to set more than just title, author, subject etc. then you need to look outside the HTML spec for inspiration:

The Dublin Core™ Elements are the normal gateway to more advanced metadata usage in HTML. BFO Publisher supports the approach recommended at https://www.dublincore.org/specifications/dublin-core/usageguide/2000-07-16/simple-html/ for embedding these properties (and of course this isn’t limited to Dublin Core). The only requirements here are:

SVG has a native method for embedding structured metadata - the <metadata> element contains RDF content, which is directly embeddable into the XMP object.

There’s no direct equivalent to this tag in HTML, but there is a recognised approach for embedding arbitrary XML in a PDF: the <script> tag.

Set the type of the script to application/rdf+xml and any content within the script tag will be parsed as an RDF (an individual RDF description can also be used, as shown here). This functions identically to the SVG <metadata> element.

As an alternative to embedding the XML directly into the file, a <link rel="meta"> can be used - the content is the same as with <script>, but this time it’s stored in an external file. Although this technique is fairly widely used it’s not standardized, but it particularly useful when building an XMP document as it lets us import boilerplate sections of XMP, such as extension schemas required for PDF/A-3.

As mentioned above, typically metadata in the document applies to the document as a whole. But this isn’t always the case. For example, in this example we have an SVG inside an HTML document, each with its own title

This works because the <svg> element is a metadata subject - an element that will "own" any metadata properties set within it. If the PDF is created with tags (for example, by setting the bfo-pdf-tagged environment variable to any value), then the tag corresponding to the SVG in the generated PDF will have its own XMP metadata.

Which elements are metadata subjects is determined by the -bfo-metadata-subject CSS property.

By default, <svg>, <object>, <html>, <img> and <iframe> elements are all metadata subjects because the user-agent stylesheet defines this rule:

Any element with -bfo-metadata-subect set to the document location will become a metadata-subject. To reverse this, set -bfo-metadata-subject: none.

Note that replaced content like images, video and audio will always form metadata subjects, and will be initialised with metadata stored in the source file. So when embedding a JPEG that includes XMP metadata, the metadata will automatically set stored in the PDF.

Fonts are loaded exactly as specified in https://www.w3.org/TR/css-fonts-4/, which is fully supported except for the sections relating to variables fonts. The deprecated embedded-opentype and svg font formats are not supported.

Some features of OpenType are unsupported, and these can be tested using the font-tech() query from https://www.w3.org/TR/css-conditional-5/#at-supports-ext or the the tech() function from https://www.w3.org/TR/css-fonts-4/#font-technologies-formats. The full list is below.

As OpenType Variable fonts are unsupported, the CSS properties font-variation-settings and font-optical-sizing are unrecognised, as are the font-named-instance and font-variation-settings descriptors.

Hyphenation is pre-supported for a number of languages, using the code and Hyphenation patterns from Apache FOP. Those patterns in turn were derived from TeX.

New hyphenation patterns can be loaded using a <link> element, as shown below. Either the FOP-style XML format (with a root element of <hyphenation-info>) or UTF-8 TeX patterns (which should look like \patterns{ …​ } - some examples) can be used.

Language matching is done using standard BCP47 rules; setting lang="en-GB-oxendict" will look first for a hyphenation dictionary with that exact language tag, falling back to en-GB then en. Hyphenation requires a language to be set: with no lang attribute (set or inherited), no hyphenation will take place.

PDF itself has long supported calibrated colors, and allows them to be defined in CIELab, or by way of an embedded ICC profile. So long as they’re within gamut, any calibrated color can be converted to any other without loss. Which means we’re able to support all the colors now available in CSS, also without loss.

With the explosion of new color-spaces available we won’t list every syntax here - if it’s in the specification, we support it. The following table shows how each is stored in PDF.

BFO Publisher ships with the reduced-size ICC profiles for the various RGB spaces listed above, created and placed into the public domain at https://github.com/saucecontrol/Compact-ICC-Profiles.

CSS Color 5 defines a syntax for device-dependent CMYK color - the only type of uncalibrated color available to CSS.

As of 2022 this syntax is widely support by other print CSS engines, although not yet by browsers. Another common syntax which was in wide use before the standardization in CSS is the cmyk() function, which is not supported in BFO Publisher by default. However it can be added by setting the bfo-sys-colors environment variable:

For example to use the legacy cmyk() function to define CMYK color:

Device-dependent color is fine if you’re happy with whatever pigments the printer has, but if you want calibrated CMYK color you will need to reference an ICC Profile by its URL.

For example, to generate CMYK color that is calibrated to "FOGRA 39", also variously known as ISO12647-2:2004 or "ISO Coated v2", you would need the URL of a suitable FOGRA39 ICC profile.

The @color-profile at rule is defined in CSS Color 5, and takes a profile name - which must begin with a double-hyphen - and a single property, src, which is the URL of the ICC profile to embed. To reference this new color-space use the standard CSS color() function as shown.

While CSS allows any type of ICC profile in theory, PDF only accepts CMYK, RGB or grayscale profiles that are of type prtr or mntr - printer and monitor, not scanner or other types intended for input devices rather than output.

The @color-profile rule can also be used to to anchor any device-cmyk colors to an ICC profile. This is required for PDF/A, PDF/UA and PDF/X documents that make use of uncalibrated CMYK. It’s identical to the example shown above except the name is device-cmyk:

We strongly recommend this approach for CMYK content instead of using the color() function; it’s simpler to manage (device-cmyk is easier to remember than a custom name), causes less problems with overprint, and will also catch any CMYK images that don’t reference an ICC profile which would otherwise remain uncalibrated.

CSS does not yet have a syntax for spot colors - also called separations, these can be thought of as additional pigments which are added to the printer alongside Cyan, Magenta, Yellow and Black.

To define spot colors in BFO Publisher, we’ve added two custom descriptors to the @color-profile rule which can be used instead of src: -bfo-components and -bfo-fallback:

These properties takes a comma-separated list of component names - the name of the ink, e.g. Pantone Reflex Blue C, and their corresponding fallback colors. The two lists should be the same length, and in the vast majority of cases they will both be a single item, to define a Spot color (lists of more than one ink define what’s called a Device-N color in PDF parlance).

The fallback color(s) should typically be in device-cmyk or another CMYK space, but RGB is also allowed. More exotic spaces such as Lab and LCH can be used, but any space that is stored in PDF using the Lab color-space is a bit complicated when it comes to gradients, so be careful. Typically the Spot color name is a well known name from the PANTONE™ range or similar, and is being used because the intended output device is aware of it colorimetry. The fallback will only be used on a device that doesn’t know about that ink, such as a screen or regular desktop printer, so an approximate device-cmyk() is fine.

Once you’ve defined a new @color-profile rule with both two properties, you can use it like any other.

If you want to create a gradient between two spot colors, or between a spot color and a process color pigment, create a @color-profile rule with all the required components of the gradient. Your new color-space can have as many components as you like - as we’re typically using additive colors any 0 values mean no ink, so keep the component at zero to disable it. However that all gets a bit complex, so the example here just show two inks.

Another use for Spot colors is to convey special pseudo-colors, which are really just instructions for the output-device: perhaps representing cut or score lines, for example, or an area to apply varnish or glue. Spot colors with overprint are a good choice here aa they allow these lines to be marked without interfering in any other color on the page. Drawing these on a PDF Layer allows them to be easily removed during proofing.

Setting -bfo-overprint to true in a @color-profile ensures that any colors created in that color-space are drawn with overprint. Overprinting is a concept unique to print; normally any inks drawn on a page replace all other inks in that area. When overprinting, only the inks in use by that color are replaced. It’s a difficult one to visualise on screen, but take a close look at the color components to get an understanding - the example shows drawing first in a CMYK color, then overwriting that with a spot-color in our custom colorspace: first normally, then with overprint.

To put all this together, imagine we want to to create our PDF with a special Fold pseudo-color which indicates to our ISO19593-aware print workflow that a fold should be made at that point. We don’t want this fold line to obscure the color behind it - we want it to overprint.

Finally, printers sometimes make use of registration black - a color which uses all inks available, so that the marks will appear on all plates (the term rich black is sometimes heard too, which is device-cmyk(1 1 1 1). The two are identical unless spot colors are used in the document - spot-color plates will not be marked by rich black, only registration black).

We’ve added a special color-profile to the list predefined in CSS Color 4, called registration. Printer marks (see the marks CSS property) are drawn in this color.

Key Store information can also be taken from an HSM (Hardware Security Module) - in fact, this is a requirement for signatures meeting the standards of the Adobe Approved Trusted List (AATL). We’ve written more on this topic at https://bfo.com/blog/2019/09/23/perfect_pdf_digital_signatures_eu_style/

The only change required to use a PKCS#11 hardware token is changing the URL of the Key Store to use the pkcs11 scheme, as defined in https://tools.ietf.org/html/rfc7512

RFC7512 describes a number of parameters but not all are available for use with the Java PKCS#11 interface. Those that do apply are described here.

Other parameters may be specified but will be ignored.

Each of the parameters specified will take their default values from an environment variable of the form bfo-ext-signature-NNN where NNN is the parameter name. This allows information which might not be available to the document author, such as the path to the keystore, to be specified in advance.