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	#	Type	Description
`href`	1	`xs:anyURI`	Reference 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.2 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 1.0)

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/Pipeline	Description
`code-docgen-dir.xpl`	Runs the `$xdoc/code-docgen.xpl` transform over multiple files in a directory.
`code-docgen.xpl`	Takes an XML document (XSL, XSD, XProc, ordinary XML) and generates documentation out of it.
`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.
`xml-description.xpl`	Takes a document that describes an XML document, using special markup for this, and turns this into DocBook.

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

Port	Type	Primary?	Description
`source`	in	yes	The triggering `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

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

Port	Type	Primary?	Description
`source`	in	yes	The document to generate documentation for, wrapped in an `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

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

Port	Type	Primary?	Description
`source`	in	yes	The document containing the parts to include, wrapped in an `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

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

Port	Type	Primary?	Description
`source`	in	yes	The document containing the XML description, wrapped in an `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

3.3 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/Pipeline	Description
`code-docgen-dir.xpl`	Runs the `$xdoc/code-docgen.xpl` transform over multiple files in a directory.
`code-docgen.xpl`	Takes an XML document (XSL, XSD, XProc, ordinary XML) and generates documentation out of it.
`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.
`xml-description.xpl`	Takes a document that describes an XML document, using special markup for this, and turns this into DocBook.

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

Port	Type	Primary?	Description
`source`	in	yes	The triggering `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

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

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.

Port	Type	Primary?	Description
`source`	in	yes	The document to generate documentation for, wrapped in an `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

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

Port	Type	Primary?	Description
`source`	in	yes	The document containing the parts to include, wrapped in an `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

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

Port	Type	Primary?	Description
`source`	in	yes	The document containing the XML description, wrapped in an `xdoc:transform` element.
`result`	out	yes	The resulting DocBook output.

3.4 Writing your own `xdoc` transformations

To add an xdoc transform of your own you need to write an XSLT stylesheet or an XProc pipeline.
Such a stylesheet or transformation gets the *full* <xdoc:transform> element as its input. It can inspect the <xdoc:transform> root element itself for its attributes.
The <xdoc:transform> element has an additional attribute xdoc:base-uri-source that holds the URI of the source document. Useful when resolving other URI s.
The output of the stylesheet/pipeline must be the resulting (valid!) DocBook.
If the resulting DocBook contains multiple elements you can wrap them all in an <xdoc:GROUP> element to make the result a single well-formed document. The <xdoc:GROUP> wrapper is removed later on by the xdoc processing.
You must reference your stylesheet or pipeline using <xdoc:transform>'s href attribute.

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:

City	Temperature (C)
Amsterdam	20
Stavanger	-5

3 xdoc transforms

3.1 Running an xdoc transform

3.2 Built-in xdoc transformations (XProc 1.0)

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

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

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

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

3.3 Built-in xdoc transformations (XProc 3.0)

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

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

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

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

3.4 Writing your own xdoc transformations

3 `xdoc` transforms

3.1 Running an `xdoc` transform

3.2 Built-in `xdoc` transformations (XProc 1.0)

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

3.2.2 XProc (1.0) pipeline: `code-docgen.xpl`

3.2.3 XProc (1.0) pipeline: `include-docbook.xpl`

3.2.4 XProc (1.0) pipeline: `xml-description.xpl`

3.3 Built-in `xdoc` transformations (XProc 3.0)

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

3.3.2 XProc (3.0) pipeline: `code-docgen.xpl`

3.3.3 XProc (3.0) pipeline: `include-docbook.xpl`

3.3.4 XProc (3.0) pipeline: `xml-description.xpl`

3.4 Writing your own `xdoc` transformations