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 (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:

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:

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.