2.1 Getting started

The template/ sub-directory of xtpxlib-xdoc contains several template files that can be used a starting point. These templates also declare the necessary namespace http://www.xtpxlib.nl/ns/xdoc, bound to the prefix xdoc:.

Use one of the XProc (1.0) processing pipelines to process an xdoc source into DocBook, PDF or HTML. For instance xdoc-to-docbook will turn your xdoc source into "pure" DocBook.

2.2 Validation

The xtpxlib-xdoc component contains an enhanced DocBook NVDL schema, xsd/docbook/docbook.nvdl, that allows the xdoc extensions.

The template files in the template/ sub-directory reference this schema. Don't forget to change this reference and keep it valid if you copy such a template to a directory of your own!

2.3 Parameter substitution

The xdoc framework performs parameter substitution. ${parameter-name} and {$parameter-name} (both mean the same) are substituted with the parameter's value (if it exists). Substitution takes place in attribute and text values. To stop such a ${…} or {$…} construction from being substituted, double the opening curly brace ({{).

The xdoc toolchain automatically creates a number of parameters:

Parameter Description Example value(s)
DATETIME The date and time the toolchain executed in YYYY-MM-DD hh:mm:ss format. 2019-11-11 12:12:12
DATE The date part of the DATETIME parameter. 2019-11-11
TIME The time part of the DATETIME parameter. 12:12:12
HREF-SOURCE The main source's filename. C:/my/path/sourcedoc.xml
/my/path/sourcedoc.xml

To specify your own parameters, create an XML document that looks like this:

<parameters>
  <parameter name="my-parameter">
    <value>Some value…</value>
  </parameter>
</parameters>

The parameter XML format has several additional features, like filtering and grouping values. It's also namespace independent and might be embedded in a bigger document. See the format's description for more information.

A reference to such a parameter document must be passed as option href-parameters to one of the processing pipelines.

To see which parameters are available in your xdoc pipelines, add the following to your document:

<xdoc:dump-parameters type="table"/>

The documentation you're looking at is also produced with the xdoc mechanism. The result of a parameter dump during its build process is:

ParameterValue
DATE2020-05-01
DATETIME2020-05-01 15:04:30
HREF-SOURCEC:/Data/Erik/work/xatapult/xtpxlib-xdoc/doc/source/xtpxlib-xdoc-chapter-instructions.xml
TIME15:04:30
active-componentsxtpxlib-common xtpxlib-container xtpxlib-xoffice xtpxlib-xdoc
author-email-addresserik@xatapult.com
author-nameErik Siegel
component-current-release-date2020-05-01
component-current-release-version1.1
component-display-namextpxlib-xdoc
component-documentation-urihttps://xdoc.xtpxlib.org
component-git-site-urihttps://github.com/xatapult/xtpxlib-xdoc
component-git-urigit@github.com:xatapult/xtpxlib-xdoc.git
component-namextpxlib-xdoc
component-titleDocBook publication toolchain
library-nameXatapult XML Library
licenseGNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007
owner-company-git-site-urihttps://github.com/xatapult
owner-company-nameXatapult Content Engineering
owner-company-phone+31 6 53260792
owner-company-websitehttp://www.xatapult.com

You can also specify type="comment". As the name implies, the parameters will be added as an XML comment so you'll have to dive into the produced DocBook to see them.

2.4 xdoc transforms

An xdoc transform is an XSLT stylesheet or XProc (1.0) pipeline that is triggered from your source document and inserts generated DocBook contents. There are several of these transforms built into the xtpxlib-xdoc component but its also easy to write one of your own. Detailed information can be found here.

As an example: xtpxlib-xdoc contains transforms to extract documentation from XML documents and programs. Among others, the documentation sections for the pipelines and libraries are generated with this. Now assume you want to insert the documentation of the xdoc-to-docbook pipeline somewhere in a document of your own. You could do this by adding a reference to the xdoc-to-docbook transform to your xdoc source:

<xdoc:transform href="$xdoc/code-docgen.xpl" filecomponents="2">
  <xi:include href="../../xpl/xdoc-to-docbook.xpl"/>
</xdoc:transform>

The result will be:

XProc (1.0) pipeline: xdoc-to-docbook.xpl

File: xpl/xdoc-to-docbook.xpl

Type: xdoc:xdoc-to-docbook

Pipeline that transforms a DocBook source containing xdoc extensions into "pure" DocBook format.

PortTypePrimary?Description
sourceinyesThe DocBook source with xdoc extensions
resultoutyesThe resulting DocBook
OptionRq?DefaultDescription
href-parameters ()Optional reference to a document with parameter settings. See here for details.
parameter-filters ()Optional filter settings for processing the parameters. Format: name=value|name=value|….