2 Instructions

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 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. Here is a dump of all current parameters. The upper-case ones are generated, the lower-case ones come from the component's information file (`component-info.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 XProc pipelines.

To see which parameters are available in your xdoc pipelines, add the following to your document (this instruction was used to generate the parameter table above):

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

You can also specify type="comment". As the name implies, the parameters will now 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 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. 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.

Historically (from the XProc-1.0-only days), `xdoc` transformations are in a subdirectory called `transforms`. To allow smooth migration from XProc 1.0 to XProc 3.0, the XProc 3.0 code that finds the transformations automatically changes any path component `/transforms/` into `/transforms3/`. This allows an `xdoc` source to (still) reference the older XProc 1.0 transformations (in `transforms/`) but auto magically get the XProc 3.0 ones (in `transforms3/`).