3 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.

3.1 Running an xdoc transform

The <xdoc:transform>extension element runs an xdoc transformation (either XProc (1.0) or XSLT (2.0 or 3.0)). It is completely replaced by the outcome of the transformation.

<xdoc:transform href = xs:anyURI
                (any)? >
  <!-- (Optional) XML to transform and/or an <xi:include> element to load this from an external source. -->
</xdoc:transform>

 

Attribute#TypeDescription
href1xs:anyURIReference to the actual transformation. Relative names are resolved against the location of the source document.
This file's extension determines whether an XProc 1.0 (extension: .xpl) or an XSLT (extension: .xsl) is done.
A value that starts with $xdoc is assumed to be an xtpxlib-xdoc built-in transformation (e.g. href="$xdoc/code-docgen.xpl"). See also 3.3 Built-in xdoc transformations (XProc 1.0).
(any)?Often transformations specify additional attributes on the <xdoc:transform> element to parametrize their functionality. Any additional attribute is allowed here.

3.2 Built-in xdoc transformations (XProc 3.0)

The xtpxlib-xdoc has several transforms built in. You also reference these by prefixing their name with $xdoc, for instance $xdoc/code-docgen.xpl. If you use the XProc 3.0 `xdoc` pipelines, these transforms are automatically used.

Module/PipelineDescription
code-docgen-dir.xplRuns the $xdoc/code-docgen.xpl transform over multiple files in a directory.
code-docgen.xplTakes an XML document (XSL, XSD, XProc, ordinary XML) and generates documentation out of it.
include-docbook.xplTakes an XML document and unwraps the root element from it. It then copies all the children to the output, with the exception of any db:info elements.
xml-description.xplTakes a document that describes an XML document, using special markup for this, and turns this into DocBook.

3.2.1 XProc (3.0) pipeline: code-docgen-dir.xpl

File: transforms3/code-docgen-dir.xpl

Type: xdoc:code-docgen-dir

Runs the $xdoc/code-docgen.xpl transform over multiple files in a directory.

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/code-docgen-dir.xpl"
   dir="…"
   depth="…"
   filter="…"
   toc-only="…"
   id-suffix="…" >

  • @dir: Directory to process

  • @depth: (integer, default -1) The depth in traversing the directory tree.

    • When le 0, @dir and all its subdirectories are processed.

    • When eq 1, only @dir is processed.

    • When gt 1, the sub-directories up to this depth are processed.

  • @filter: optional regexp filter (e.g. get only XProc files with filter="\.xpl$")

  • @toc-only: (boolean, default false) Whether to produce a ToC table only.

  • @id-suffix: Optional suffix for creating an id based on the filename.

PortTypePrimary?Description
sourceinyesThe triggering xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.2.2 XProc (3.0) pipeline: code-docgen.xpl

File: transforms3/code-docgen.xpl

Type: xdoc:code-docgen

Takes an XML document (XSL, XSD, XProc, ordinary XML) and generates documentation out of it.

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/code-docgen.xpl"
   filecomponents="…"
   header-level="…"
   add-table-titles="…"
   sublevels="…"
   id="…"
   id-suffix="…" >
  <xi:include href="path/to/document/to/generate/documentation/for"/>
</xdoc:transform>

  • @filecomponents: (integer, default 0)Determines the display of the filename:

    • When lt 0, no filename is displayed

    • When eq 0, the full filename (with full path) is displayed

    • When gt 0, this number of filename components is displayed. So 1 means filename only, 2 means filename and direct foldername, etc.

  • @header-level: (integer, default 0)Determines what kind of DocBook section is created:

    • When le 0, no separate section is created, all titles will be output as bridgehead elements.

    • Otherwise a title with this level is created (e.g. header-level="1" means a sect1 element).

  • @add-table-titles: (boolean, default false) Whether to add titles to generated tables.

  • @sublevels: (boolean, default true) If true only the main section will be a "real" section. All sublevels will become bridgeheads.

  • @id: Optional identifier of this section. If absent the id will become the document's filename, optionally suffixed with @id-suffix.

  • @id-suffix: Optional suffix for creating an id based on the filename.

If the format to document has means to add documentation of itself (like XProc (p:documentation) or XML Schema (xs:annotation)), this is used. If there is no such thing (like for XSLT and straight XML), comments starting with a tilde (~) are used.

All descriptions and documentation sections can contain simple Markdown.

The following formats are supported

  • XML documents: only the header comment is used.

  • XSLT (2.0 and 3.0) stylesheets: document all exported parameters, variables, functions and named templates. Something is supposed to be for export if its not in the no or local namespace.

  • XProc pipelines and libraries

  • XML Schemas: Uses the global annotation and lists the global elements using their annotations.

PortTypePrimary?Description
sourceinyesThe document to generate documentation for, wrapped in an xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.2.3 XProc (3.0) pipeline: include-docbook.xpl

File: transforms3/include-docbook.xpl

Takes an XML document and unwraps the root element from it. It then copies all the children to the output, with the exception of any db:info elements.

It is the responsibility of the author to make sure that everything that results is in the DocBook (http://docbook.org/ns/docbook) namespace!

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/include-docbook.xpl>
  <xi:include href="path/to/xml/to/include.xml"/>
</xdoc:transform>
PortTypePrimary?Description
sourceinyesThe document containing the parts to include, wrapped in an xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.2.4 XProc (3.0) pipeline: xml-description.xpl

File: transforms3/xml-description.xpl

Takes a document that describes an XML document, using special markup for this, and turns this into DocBook.

A schema for this markup format can be found in xsd/element-description.xml.

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/xml-description.xpl>
  <xi:include href="path/to/xml/description.xml"/>
</xdoc:transform>
PortTypePrimary?Description
sourceinyesThe document containing the XML description, wrapped in an xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.3 Built-in xdoc transformations (XProc 1.0)

WARNING: XProc 1.0 support is considered deprecated and will be removed in the near future!

The xtpxlib-xdoc has several transforms built in that use XProc 1.0. You can easily reference these by prefixing their name with $xdoc, for instance $xdoc/code-docgen.xpl. If you use the XProc 1.0 `xdoc` pipelines, these transforms are automatically used.

Module/PipelineDescription
code-docgen-dir.xplRuns the $xdoc/code-docgen.xpl transform over multiple files in a directory.
code-docgen.xplTakes an XML document (XSL, XSD, XProc, ordinary XML) and generates documentation out of it.
include-docbook.xplTakes an XML document and unwraps the root element from it. It then copies all the children to the output, with the exception of any db:info elements.
xml-description.xplTakes a document that describes an XML document, using special markup for this, and turns this into DocBook.

3.3.1 XProc (1.0) pipeline: code-docgen-dir.xpl

File: transforms/code-docgen-dir.xpl

Runs the $xdoc/code-docgen.xpl transform over multiple files in a directory.

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/code-docgen-dir.xpl"
   dir="…"
   depth="…"
   filter="…"
   toc-only="…"
   id-suffix="…" >

  • @dir: Directory to process

  • @depth: (integer, default -1) The depth in traversing the directory tree.

    • When le 0, @dir and all its subdirectories are processed.

    • When eq 1, only @dir is processed.

    • When gt 1, the sub-directories up to this depth are processed.

  • @filter: optional regexp filter (e.g. get only XProc files with filter="\.xpl$")

  • @toc-only: (boolean, default false) Whether to produce a ToC table only.

  • @id-suffix: Optional suffix for creating an id based on the filename.

All (other) attributes are passed to code-docgen.xpl.

PortTypePrimary?Description
sourceinyesThe triggering xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.3.2 XProc (1.0) pipeline: code-docgen.xpl

File: transforms/code-docgen.xpl

Type: xdoc:code-docgen

Takes an XML document (XSL, XSD, XProc, ordinary XML) and generates documentation out of it.

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/code-docgen.xpl"
   filecomponents="…"
   header-level="…"
   add-table-titles="…"
   sublevels="…"
   id="…"
   id-suffix="…" >
  <xi:include href="path/to/document/to/generate/documentation/for"/>
</xdoc:transform>

  • @filecomponents: (integer, default 0)Determines the display of the filename:

    • When lt 0, no filename is displayed

    • When eq 0, the full filename (with full path) is displayed

    • When gt 0, this number of filename components is displayed. So 1 means filename only, 2 means filename and direct foldername, etc.

  • @header-level: (integer, default 0)Determines what kind of DocBook section is created:

    • When le 0, no separate section is created, all titles will be output as bridgehead elements.

    • Otherwise a title with this level is created (e.g. header-level="1" means a sect1 element).

  • @add-table-titles: (boolean, default false) Whether to add titles to generated tables.

  • @sublevels: (boolean, default true) If true only the main section will be a "real" section. All sublevels will become bridgeheads.

  • @id: Optional identifier of this section. If absent the id will become the document's filename, optionally suffixed with @id-suffix.

  • @id-suffix: Optional suffix for creating an id based on the filename.

If the format to document has means to add documentation of itself (like XProc (p:documentation) or XML Schema (xs:annotation)), this is used. If there is no such thing (like for XSLT and straight XML), comments starting with a tilde (~) are used.

All descriptions and documentation sections can contain simple Markdown.

The following formats are supported

  • XML documents: only the header comment is used.

  • XSLT (2.0 and 3.0) stylesheets: document all exported parameters, variables, functions and named templates. Something is supposed to be for export if its not in the no or local namespace.

  • XProc pipelines and libraries

  • XML Schemas: Uses the global annotation and lists the global elements using their annotations.

PortTypePrimary?Description
sourceinyesThe document to generate documentation for, wrapped in an xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.3.3 XProc (1.0) pipeline: include-docbook.xpl

File: transforms/include-docbook.xpl

Takes an XML document and unwraps the root element from it. It then copies all the children to the output, with the exception of any db:info elements.

It is the responsibility of the author to make sure that everything that results is in the DocBook (http://docbook.org/ns/docbook) namespace!

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/include-docbook.xpl>
  <xi:include href="path/to/xml/to/include.xml"/>
</xdoc:transform>
PortTypePrimary?Description
sourceinyesThe document containing the parts to include, wrapped in an xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.3.4 XProc (1.0) pipeline: xml-description.xpl

File: transforms/xml-description.xpl

Takes a document that describes an XML document, using special markup for this, and turns this into DocBook.

A schema for this markup format can be found in xsd/element-description.xml.

Typical usage (within an xdoc source document):

<xdoc:transform href="$xdoc/xml-description.xpl>
  <xi:include href="path/to/xml/description.xml"/>
</xdoc:transform>
PortTypePrimary?Description
sourceinyesThe document containing the XML description, wrapped in an xdoc:transform element.
resultoutyesThe resulting DocBook output.

3.4 Writing your own xdoc transformations

Here is a simple example of something that is actually quite useful. Tables in DocBook are complex things. When you to have format the same kind of data over and over again in a table, it becomes very boring and hard to keep consistent and maintainable. Using xdoc transforms you can automate the data to DocBook part.

Assume we have, all over the document, weather data, that comes in this source format:

<weather-data>
  <data city="Amsterdam" temp="20"/>
  <data city="Stavanger" temp="-5"/>
</weather-data>

You want to show this as tables. The following XSLT stylesheet (called transform-weather-data.xsl) will do the xdoc transform trick. As its input it gets the weather data wrapped in the <xdoc:transform> element (see below).

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:xdoc="http://www.xtpxlib.nl/ns/xdoc"
  xmlns="http://docbook.org/ns/docbook">

  <xsl:template match="/">
    <table>
      <title>Example weather data</title>
      <tgroup cols="2">
        <colspec colwidth="4cm"/>
        <colspec/>
        <thead>
          <row>
            <entry>
              <para>City</para>
            </entry>
            <entry>
              <para>Temperature (C)</para>
            </entry>
          </row>
        </thead>
        <tbody>
          <xsl:for-each select="/xdoc:transform/weather-data/data">
            <row>
              <entry>
                <para>
                  <xsl:value-of select="@city"/>
                </para>
              </entry>
              <entry>
                <para><xsl:value-of select="@temp"/></para>
              </entry>
            </row>
          </xsl:for-each>
        </tbody>
      </tgroup>
    </table>
  </xsl:template>

</xsl:stylesheet>

In your document you add:

<xdoc:transform href="path/to/transform-weather-data.xsl">
  <xi:include href="path/to/your/weather/data.xml"/>
</xdoc:transform>

And the result for this example is:

CityTemperature (C)
Amsterdam20
Stavanger-5