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.
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!
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:
Parameter | Value |
---|---|
DATE | 2020-11-30 |
DATETIME | 2020-11-30 13:06:20 |
HREF-SOURCE | C:/Data/Erik/work/xatapult/xtpxlib-xdoc/doc/source/xtpxlib-xdoc-chapter-instructions.xml |
TIME | 13:06:20 |
active-components | xtpxlib-common xtpxlib-container xtpxlib-xoffice xtpxlib-xdoc |
author-email-address | erik@xatapult.com |
author-name | Erik Siegel |
component-current-release-date | 2020-11-30 |
component-current-release-version | 1.1.2 |
component-display-name | xtpxlib-xdoc |
component-documentation-uri | https://xdoc.xtpxlib.org |
component-git-site-uri | https://github.com/xatapult/xtpxlib-xdoc |
component-git-uri | git@github.com:xatapult/xtpxlib-xdoc.git |
component-name | xtpxlib-xdoc |
component-title | DocBook publication toolchain |
library-name | Xatapult XML Library |
license | GNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 |
owner-company-git-site-uri | https://github.com/xatapult |
owner-company-name | Xatapult Content Engineering |
owner-company-phone | +31 6 53260792 |
owner-company-website | http://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.
xdoc
transformsAn 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.
Port | Type | Primary? | Description |
---|---|---|---|
source | in | yes | The DocBook source with xdoc extensions |
result | out | yes | The resulting DocBook |
Option | Rq? | Default | Description |
---|---|---|---|
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|… . |