5 XProc 3.0 support

The xtpxlib-xdoc component contains the following XProc 3.0 pipelines:

Module/PipelineDescription
docbook-to-pdf.xplThis turns Docbook (5.1) into a PDF using FOP.
docbook-to-xhtml.xplThis turns Docbook (5.1) into XHTML.
xdoc-to-docbook.xplXProc 3.0 pipeline that transforms a DocBook source containing xdoc extensions into "pure" DocBook format.
xdoc-to-pdf.xplConvenience pipeline: Combines the xdoc-to-docbook and the docbook-to-pdf steps in one.
xdoc-to-xhtml.xplConvenience pipeline: Combines the xdoc-to-docbook and the docbook-to-xhtml steps in one.

5.1 XProc (3.0) pipeline: docbook-to-pdf.xpl

File: xpl3/docbook-to-pdf.xpl

Type: xdoc:docbook-to-pdf

This turns Docbook (5.1) into a PDF using FOP.

All necessary xdoc pre-processing (usually with xdoc-to-docbook.xpl) must have been done.

It will only convert a partial DocBook tagset.

If you don't use xdoc-to-docbook.xpl, you have to make sure to get correct xml:base attributes in, so the pipeline can find includes and images. The following XProc (1.0) code takes care of that:

<p:xinclude>
  <p:with-option name="fixup-xml-base" select="true()"/>
</p:xinclude>
<p:add-attribute attribute-name="xml:base" match="/*">
  <p:with-option name="attribute-value" select="/reference/to/source/document.xml"/>
</p:add-attribute>
PortTypePrimary?Description
sourceinyesThe Docbook source document, fully expanded (with appropriate xml:base attributes)
resultoutyesA small report thingie
OptionTypeRq?DefaultDescription
chapter-idxs:string ''Specific chapter identifier to output.
create-pdfxs:boolean true()Whether to actually create the PDF.
fop-configxs:string resolve-uri('../../xtpxlib-common/data/fop-default-config.xml', static-base-uri())Reference to the FOP configuration file
global-resources-directoryxs:string? ()Images that are tagged as role="global" are searched here (discarding any directory information in the image's URI)
href-pdfxs:stringyesThe name of the resulting PDF file, as a URI (an absolute path must have file:// in front).
href-xsl-foxs:string? ()If set, writes the intermediate XSL-FO to this href (so you can inspect it when things go wrong in FOP)
main-font-sizexs:integer 10Main font size as an integer. Usual values somewhere between 8 and 10.
output-typexs:string 'a4'Output type. Use either a4 or sb (= standard book size)
preliminary-versionxs:boolean false()If true, adds a preliminary version marker and output any db:remark elements. If false, output of db:remark elements will be suppressed.

5.2 XProc (3.0) pipeline: docbook-to-xhtml.xpl

File: xpl3/docbook-to-xhtml.xpl

Type: xdoc:docbook-to-xhtml

This turns Docbook (5.1) into XHTML.

All necessary xdoc pre-processing (usually with xdoc-to-docbook.xpl) must have been done.

It will only convert a partial DocBook tagset.

The resulting XHTML will not be directly useable, post-processing the result into a complete and correct HTML page is necessary. The result of this pipeline consists of nested div elements. There is no surrounding html or body element.

PortTypePrimary?Description
sourceinyesThe docbook source document.
resultoutyesThe resulting XHTML

5.3 XProc (3.0) pipeline: xdoc-to-docbook.xpl

File: xpl3/xdoc-to-docbook.xpl

Type: xdoc:xdoc-to-docbook

XProc 3.0 pipeline that transforms a DocBook source containing xdoc extensions into "pure" DocBook format.

PortTypePrimary?Description
sourceinyesThe DocBook source with xdoc extensions
resultoutyesThe resulting DocBook.
OptionTypeRq?DefaultDescription
alttargetxs:string? ()The target for applying alternate settings.
href-parametersxs:string? ()Optional reference to a document with parameter settings. See here for details.
parameter-filters-mapmap(xs:string, xs:string) map{}Optional filter settings for processing the parameters.

5.4 XProc (3.0) pipeline: xdoc-to-pdf.xpl

File: xpl3/xdoc-to-pdf.xpl

Type: xdoc:xdoc-to-pdf

Convenience pipeline: Combines the xdoc-to-docbook and the docbook-to-pdf steps in one.

PortTypePrimary?Description
sourceinyesThe Docbook source, with option al xdoc extensions.
resultoutyesA small report thingie
OptionTypeRq?DefaultDescription
alttargetxs:string? ()The target for applying alternate settings.
chapter-idxs:string ''Specific chapter identifier to output.
create-pdfxs:boolean true()Whether to actually create the PDF.
fop-configxs:string resolve-uri('../../xtpxlib-common/data/fop-default-config.xml', static-base-uri())Reference to the FOP configuration file
global-resources-directoryxs:string? ()Images that are tagged as role="global" are searched here (discarding any directory information in the image's URI)
href-docbookxs:string? ()If set, writes the intermediate full DocBook to this href (so you can inspect it when things go wrong)
href-parametersxs:string? ()Optional reference to a document with parameter settings. See here for details.
href-pdfxs:stringyesThe name of the resulting PDF file, as a URI (an absolute path must have file:// in front).
href-xsl-foxs:string? ()If set, writes the intermediate XSL-FO to this href (so you can inspect it when things go wrong in FOP)
main-font-sizexs:integer 10Main font size as an integer. Usual values somewhere between 8 and 10.
output-typexs:string 'a4'Output type. Use either a4 or sb (= standard book size)
parameter-filters-mapmap(xs:string, xs:string) map{}Optional filter settings for processing the parameters.
preliminary-versionxs:boolean false()If true, adds a preliminary version marker and output any db:remark elements. If false, output of db:remark elements will be suppressed.

5.5 XProc (3.0) pipeline: xdoc-to-xhtml.xpl

File: xpl3/xdoc-to-xhtml.xpl

Type: xdoc:xdoc-to-pdf

Convenience pipeline: Combines the xdoc-to-docbook and the docbook-to-xhtml steps in one.

PortTypePrimary?Description
sourceinyesThe Docbook source, with option al xdoc extensions.
resultoutyesThe resulting XHTML.
OptionTypeRq?DefaultDescription
alttargetxs:string? ()The target for applying alternate settings.
href-docbookxs:string? ()If set, writes the intermediate full DocBook to this href (so you can inspect it when things go wrong)
href-parametersxs:string? ()Optional reference to a document with parameter settings. See here for details.
parameter-filters-mapmap(xs:string, xs:string) map{}Optional filter settings for processing the parameters.
Module/PipelineDescription
xtpxlib-xdoc.mod.xplLibrary with support pipelines for xdoc and related conversions.

5.6 XProc (3.0) library: xtpxlib-xdoc.mod.xpl

File: xpl3mod/xtpxlib-xdoc.mod/xtpxlib-xdoc.mod.xpl

Library with support pipelines for xdoc and related conversions.

PrefixNamespace URI
xdochttp://www.xtpxlib.nl/ns/xdoc

5.6.1 Step: xdoc:markdown-to-docbook

Converts the contents of xdoc:MARKDOWN elements into DocBook.

This pipeline checks the incoming XML for xdoc:MARKDOWN elements. The contents of these elements is assumed to contain Markdown. The pipeline tries to convert this into DocBook. The xdoc:MARKDOWN element is removed/unwrapped.

The following rules apply:

  • The contents of an xdoc:MARKDOWN element is stringified (so any child elements are lost).

  • The resulting text can be indented, using space characters only (no tabs!). The non-empty line with the minimum indent is assumed to be its left margin.

  • Only simple Markdown is supported. Specifically:

    • Inline markup for emphasis, bold, code, etc.

    • Links. A link target starting with a % is handled as an internal link (the @xml:id of something in the encompassing DocBook).

    • Code blocks (using three consecutive back-ticks)

    • Headers (these are all converted into the same DocBook bridgehead elements)

  • Specifically not supported (yet?) are tables.

If you add an header-only="true" attribute to the xdoc:MARKDOWN element, only the first paragraph will be output.

PortTypePrimary?Description
sourceinyesAny XML that might contain xdoc:MARKDOWN elements for conversion.
resultoutyesThe same XML but with the xdoc:MARKDOWN element's contents converted into DocBook.