DocBook Transclusion

Jirka Kosek

Norman Walsh

12 May 2021

Table of Contents

1 Introduction
2 Transclusion processing
Appendix A. Using XInclude 1.1 features for your content
Appendix B. Special ID/IDREF processing
Appendix C. DocBook schema with support for transclusions
Appendix D. Change log
Bibliography

1 Introduction

This document describes the syntax, semantics, and processing model for the DocBook transclusion mechanism. Please be aware that this is a working draft – everything described below might change or disappear completely. This proposal addresses the issues described in Requirements for transclusion in DocBook. The DocBook TC welcomes feedback on this draft, especially from users and developers of DocBook authoring and processing tools. Please direct your comments to the DocBook mailing list by sending email to docbook@lists.oasis-open.org.

ⓘ

Note

Previous version of this draft proposed the new elements ref and def for implementing transclusions. Meanwhile DocBook TC decided that transclusions should rely as much as possible on standard technologies. XInclude 1.1 added new features that allow to implement transclusion features on top of the XInclude. As a result transclusions were completely redesigned to be layered on top of XInclude 1.1.

This resulted in a loss of some features. For example, it's no longer possible to locally redefine text replacement (see this example from the April 20, 2014 draft of this document).

The following namespace bindings are used as prefixes in this document:

trans: DocBook transclusion namespace (http://docbook.org/ns/transclusion)
db: DocBook namespace (http://docbook.org/ns/docbook)
xi: XInclude namespace (http://www.w3.org/2001/XInclude)
local: XInclude namespace for copying attributes without a namespace (http://www.w3.org/2001/XInclude/local-attributes)

2 Transclusion processing

The processing model for transclusion is simple and cosists of the following steps:

Normal XInclude 1.1 processing on the input document.
DocBook transclusion processing on the result to fix problems such as duplicate IDs and broken cross-references.
Normal processing on the resulting document using the DocBook stylesheets or equivalent tools.

Transclusion processing is controlled by attributes from the http://docbook.org/ns/transclusion namespace. These attributes are typically inserted into a document by using the attribute copying feature of XInclude 1.1 XI11, which is described in section 4.3 Attribute Copying when processing XML of the XInclude 1.1 specification.

The transclusion processor copies documents node by node. For most nodes this is an identity transformation. The few exceptions are controlled by transclusion properties. Transclusion properties suffix and linkscope are defined for each node in the document as follows:

suffix

Defines a value to be appended to all ID values on the element (elements and attributes whose values should be treated as IDs are listed in the ID-list property)
Default is an empty string
Inherited
Can be changed by the trans:idfixup and trans:suffix attributes

linkscope

Defines how to correct ID references (elements and attributes whose values should be treated as ID references are listed in the IDREF-list property)
Allowed values are user, local, near, and global
Default value is near
Inherited
Can be changed by the trans:linkscope attribute

For each document type there are two properties, ID-list and IDREF-list, which control the transclusion process. The ID-list property defines the attributes and elements whose values should be treated as IDs. Similarly, the IDREF-list property defines the attributes and elements whose values should be treated as ID references. These properties are defined for DocBook 5.0 in Definition of ID-list and IDREF-list properties for DocBook 5.0. Transclusion processors are free to support the ID-list and IDREF-list properties with other document types, for example DocBook 4.x or TEI.

ID references identified in the IDREF-list are corrected as follows:

When linkscope=user

No adjustment is made.

When linkscope=local

The value of the suffix property is added to every ID reference as a suffix.

When linkscope=near

Each ID reference is adjusted to point to the closest element that has a matching ID.

To find the closest element, the parent element of the element that contains the ID reference is searched for a matching ID, followed by that element's descendants. If no matching ID is found, that element's parent is inspected in the same way. This continues until a match is found or the root element is reached.

When linkscope=global

Each ID reference is adjusted to point to the first element in document order that has a matching ID.

A matching ID does not mean exact string equality between ID and IDREF values. A matching ID means that the values of an ID and IDREF match after removing any added suffixes.

Transclusion properties can be set on any element using the following attributes:

trans:idfixup attribute

value none: The suffix property is set to an empty string.
value suffix: The suffix property is set to the concatenation of the inherited suffix value and the value specified in the trans:suffix attribute.
value auto: The suffix property is set to a unique value for each element.¹

trans:suffix attribute

This attribute defines the value of the suffix property used when trans:idfixup="suffix".

It's an error to use this attribute when the attribute/value pair trans:idfixup="suffix" is not also on the element.

trans:linkscope attribute

Sets the value of the linkscope property. Permitted values are: user, local, near, and global.

During the transclusion process all attributes from the transclusion namespace are removed from the resulting document.

Definition of ID-list and IDREF-list properties for DocBook 5.0

In DocBook 5.0, the ID-list and IDREF-list properties contain the attributes shown here:

ID-list

xml:id

IDREF-list

linkend, linkends, otherterm, zone, startref, arearefs, targetptr, and endterm.

The href attribute in the XLink namespace is considered a member of IDREF-list when its value begins with #.

Appendix A. Using XInclude 1.1 features for your content

The most common transclusion scenario is reuse of shared strings (see https://docbook.org/docs/transclusion-requirements/transclusion-requirements.html#uc-1). With XInclude 1.0 this could only be done using XPointer schemes that were not very interoperable. With XInclude 1.1, doing this is much easier.

Let's assume we have defined a set of shared strings in separate document (see Example A.1, Definitions stored in a separate document (definitions.001.xml)).

1 |<?xml version="1.0" encoding="UTF-8"?>
  |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  |  <title>Placeholder for definitions</title>
  |  <para>
5 |    <phrase xml:id="product-version">3.14</phrase>
  |    <phrase xml:id="product-name">FooWiz</phrase>
  |    <phrase xml:id="corp-name">ACME Inc.</phrase>
  |  </para>
  |</article>

Example A.1 Definitions stored in a separate document (definitions.001.xml)

If you transclude parts of this document as shown in Example A.2, Transclusion with duplicate IDs, you will end up with duplicate IDs. In this example, the same definition is included twice. Because the ID attributes are passed through unchanged, the ID value product-name occurs twice in the resulting document.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<article xmlns="http://docbook.org/ns/docbook" version="5.0"
   |  xmlns:xi="http://www.w3.org/2001/XInclude">
   |  <info>
 5 |    <title>Transclusions demo</title>
   |  </info>
   |  <para>The latest version of
   |    <application><xi:include href="definitions.001.xml" xpointer="product-name"/></application> from
   |    <xi:include href="definitions.001.xml" xpointer="corp-name"/>
10 |    is <xi:include href="definitions.001.xml" xpointer="product-version"/>.</para>
   |  <para>You can buy <xi:include href="definitions.001.xml" xpointer="product-name"/> in our on-line store.</para>
   |</article>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <info>
   |      <title>Transclusions demo</title>
 5 |  </info>
   |  <para>The latest version of
   |    <application>
   |         <phrase xml:base="definitions.001.xml" xml:id="product-name">FooWiz</phrase>
   |      </application> from
10 |    <phrase xml:base="definitions.001.xml" xml:id="corp-name">ACME Inc.</phrase>
   |    is <phrase xml:base="definitions.001.xml" xml:id="product-version">3.14</phrase>.</para>
   |  <para>You can buy <phrase xml:base="definitions.001.xml" xml:id="product-name">FooWiz</phrase> in our on-line store.</para>
   |</article>

Example A.2 Transclusion with duplicate IDs

XInclude 1.1 has an attribute, set-xml-id, which can be used to change or remove the xml:id attribute on included content. Example A.3, Using set-xml-id to remove the top-level ID during transclusion uses this attribute to avoid duplicate IDs.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<article xmlns="http://docbook.org/ns/docbook" version="5.0"
   |  xmlns:xi="http://www.w3.org/2001/XInclude">
   |  <info>
 5 |    <title>Transclusions demo</title>
   |  </info>
   |  <para>The latest version of
   |    <application><xi:include href="definitions.001.xml" xpointer="product-name" set-xml-id=""/></application> from
   |    <xi:include href="definitions.001.xml" xpointer="corp-name" set-xml-id=""/>
10 |    is <xi:include href="definitions.001.xml" xpointer="product-version" set-xml-id=""/>.</para>
   |  <para>You can buy <xi:include href="definitions.001.xml" xpointer="product-name" set-xml-id=""/> in our on-line store.</para>
   |</article>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <info>
   |      <title>Transclusions demo</title>
 5 |  </info>
   |  <para>The latest version of
   |    <application>
   |         <phrase xml:base="definitions.001.xml">FooWiz</phrase>
   |      </application> from
10 |    <phrase xml:base="definitions.001.xml">ACME Inc.</phrase>
   |    is <phrase xml:base="definitions.001.xml">3.14</phrase>.</para>
   |  <para>You can buy <phrase xml:base="definitions.001.xml">FooWiz</phrase> in our on-line store.</para>
   |</article>

Example A.3 Using set-xml-id to remove the top-level ID during transclusion

Another new XInclude 1.1 feature lets you override attributes on included content. Example A.4, Overriding DocBook attributes on inclusion shows how to use this feature to override effectivity attributes. This feature works by placing attributes from a specially defined namespace (http://www.w3.org/2001/XInclude/local-attributes) on the xi:include element. These attributes define the values that should be used to replace attributes of the same name, but no namespace, in the transcluded content.

Consider section (section.001.xml), which is labeled for the Linux operating system (os="linux").

1 |<?xml version="1.0" encoding="UTF-8"?>
  |<section xmlns="http://docbook.org/ns/docbook"
  |    version="5.0"
  |    os="linux">
5 |    <title>Installation</title>
  |    <para>Text</para>
  |</section>

Now we want to include this section in another document and pretend that it's actually targeted at a BSD system.

1 |<?xml version="1.0" encoding="UTF-8"?>
  |<article xmlns="http://docbook.org/ns/docbook"
  |    xmlns:xi="http://www.w3.org/2001/XInclude"
  |    xmlns:local="http://www.w3.org/2001/XInclude/local-attributes"
5 |    version="5.0">
  |  <title>Sample article</title>
  |  <xi:include href="section.001.xml" local:os="bsd"/>
  |</article>

The value of the local:os attribute replaces the value of the os attribute during the XInclude process.

1 |<?xml version="1.0" encoding="UTF-8"?>
  |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  |  <title>Sample article</title>
  |  <section version="5.0" os="bsd" xml:base="section.001.xml">
5 |      <title>Installation</title>
  |      <para>Text</para>
  |   </section>
  |</article>

Example A.4 Overriding DocBook attributes on inclusion

Appendix B. Special ID/IDREF processing

Transcluded content can contain xml:id attributes. If one fragment is transcluded more than once, then the resulting document after transclusion will contain duplicate IDs. The same problem can occur if the same ID is used in two different transcluded modules. To overcome this problem, IDs and ID references can be adjusted during the transclusion process.

The trans:idfixup attribute on the xi:include element determines how IDs are adjusted during transclusion.

Of course, if IDs are adjusted then all corresponding ID references also have to be adjusted.

These adjustments are controlled by the trans:idfixup and trans:linkscope attributes. The following examples show the effect of using those two attributes. Each example transcludes the procedure shown in Example B.1, Module with sample procedure, which contains one internal link and one external link.

1 |<?xml version="1.0" encoding="UTF-8"?>
  |<procedure xmlns="http://docbook.org/ns/docbook" xml:id="paper-insert">
  |  <title>Inserting paper into printer</title>
  |  <para>This procedure is for printer owners.
5 |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
  |  <step xml:id="s1"><para>Make sure that you have paper.</para></step>
  |  <step><para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1"/></para></step>
  |</procedure>

Example B.1 Module with sample procedure

Example B.2, Automatic ID/IDREF adjustment transcludes this module twice to show how we can deal with the duplicate ID problem.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook"
   |      xmlns:xi="http://www.w3.org/2001/XInclude"
   |      xmlns:trans="http://docbook.org/ns/transclude"
 5 |      version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
   |    <title>Buying printer</title>
   |    <para>Grab money, go to shop, ...</para>
10 |  </chapter>
   |  <chapter>
   |    <title>Quick installation guide</title>
   |    <para>Carefully follow all procedures below.</para>
   |    <xi:include href="procedure.001.xml" trans:idfixup="auto"/>
15 |  </chapter>
   |  <chapter>
   |    <title>Maintenance</title>
   |    <para>Be friendly to your printer when you speak to it.</para>
   |    <para>If the green led is blinking, please add missing paper using the following procedure.</para>
20 |    <xi:include href="procedure.001.xml" trans:idfixup="auto"/>
   |  </chapter>
   |</book>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
 5 |      <title>Buying printer</title>
   |      <para>Grab money, go to shop, ...</para>
   |  </chapter>
   |  <chapter>
   |      <title>Quick installation guide</title>
10 |      <para>Carefully follow all procedures below.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert---d1e23">
   |         <title>Inserting paper into printer</title>
   |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
15 |         <step xml:id="s1---d1e23">
   |            <para>Make sure that you have paper.</para>
   |         </step>
   |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1---d1e23"/>
20 |            </para>
   |         </step>
   |      </procedure>
   |  </chapter>
   |  <chapter>
25 |      <title>Maintenance</title>
   |      <para>Be friendly to your printer when you speak to it.</para>
   |      <para>If the green led is blinking, please add missing paper using the following procedure.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert---d1e56">
   |         <title>Inserting paper into printer</title>
30 |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |         <step xml:id="s1---d1e56">
   |            <para>Make sure that you have paper.</para>
   |         </step>
35 |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1---d1e56"/>
   |            </para>
   |         </step>
   |      </procedure>
40 |  </chapter>
   |</book>

Example B.2 Automatic ID/IDREF adjustment

Specifying db:idfixup triggers the automatic ID/IDREF fixup. All IDs in the transcluded modules are automatically suffixed to prevent ID collisions. Then, IDREFs are fixed so that links point to the nearest possible target. In Example B.2, Automatic ID/IDREF adjustment, the link from step 2 to step 1 in the procedure always points to the same instance of the procedure. However, the buy link correctly points to the target in the main document.

Example B.3, Global linkscope uses trans:linkscope="global" for the second transclusion. The result is that the link from step 2 in the second procedure links to step 1 in the first procedure.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook"
   |      xmlns:xi="http://www.w3.org/2001/XInclude"
   |      xmlns:trans="http://docbook.org/ns/transclude"
 5 |      version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
   |    <title>Buying printer</title>
   |    <para>Grab money, go to shop, ...</para>
10 |  </chapter>
   |  <chapter>
   |    <title>Quick installation guide</title>
   |    <para>Carefully follow all procedures below.</para>
   |    <xi:include href="procedure.001.xml" trans:idfixup="auto"/>
15 |  </chapter>
   |  <chapter>
   |    <title>Maintenance</title>
   |    <para>Be friendly to your printer when you speak to it.</para>
   |    <para>If green led is blinking, please add paper using the following procedure.</para>
20 |    <xi:include href="procedure.001.xml" trans:idfixup="auto" trans:linkscope="global"/>
   |  </chapter>
   |</book>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
 5 |      <title>Buying printer</title>
   |      <para>Grab money, go to shop, ...</para>
   |  </chapter>
   |  <chapter>
   |      <title>Quick installation guide</title>
10 |      <para>Carefully follow all procedures below.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert---d1e23">
   |         <title>Inserting paper into printer</title>
   |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
15 |         <step xml:id="s1---d1e23">
   |            <para>Make sure that you have paper.</para>
   |         </step>
   |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1---d1e23"/>
20 |            </para>
   |         </step>
   |      </procedure>
   |  </chapter>
   |  <chapter>
25 |      <title>Maintenance</title>
   |      <para>Be friendly to your printer when you speak to it.</para>
   |      <para>If green led is blinking, please add paper using the following procedure.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert---d1e56">
   |         <title>Inserting paper into printer</title>
30 |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |         <step xml:id="s1---d1e56">
   |            <para>Make sure that you have paper.</para>
   |         </step>
35 |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1---d1e23"/>
   |            </para>
   |         </step>
   |      </procedure>
40 |  </chapter>
   |</book>

Example B.3 Global linkscope

Example B.4, Local linkscope uses db:linkscope="local" on the first transclusion. This means that every link from this transclusion must point to an ID inside the transcluded content; no external links are allowed. Because the transcluded content does contain a link to an external ID (buy), this example is broken, since the transclusion process rewrites buy to be buy---d1e23, for which there is no corresponding target.

This method of transclusion can be useful if you are transcluding foreign content and want to isolate its links from the rest of your document.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook"
   |      xmlns:xi="http://www.w3.org/2001/XInclude"
   |      xmlns:trans="http://docbook.org/ns/transclude"
 5 |      version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
   |    <title>Buying printer</title>
   |    <para>Grab money, go to shop, ...</para>
10 |  </chapter>
   |  <chapter>
   |    <title>Quick installation guide</title>
   |    <para>Carefully follow all procedures below.</para>
   |    <xi:include href="procedure.001.xml" trans:idfixup="auto" trans:linkscope="local"/>
15 |  </chapter>
   |  <chapter>
   |    <title>Maintenance</title>
   |    <para>Be friendly to your printer when you speak to it.</para>
   |    <para>If the green led is blinking, please add paper using the following procedure.</para>
20 |    <xi:include href="procedure.001.xml" trans:idfixup="auto"/>
   |  </chapter>
   |</book>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
 5 |      <title>Buying printer</title>
   |      <para>Grab money, go to shop, ...</para>
   |  </chapter>
   |  <chapter>
   |      <title>Quick installation guide</title>
10 |      <para>Carefully follow all procedures below.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert---d1e23">
   |         <title>Inserting paper into printer</title>
   |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy---d1e23">buying one</link>.</para>  
15 |         <step xml:id="s1---d1e23">
   |            <para>Make sure that you have paper.</para>
   |         </step>
   |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1---d1e23"/>
20 |            </para>
   |         </step>
   |      </procedure>
   |  </chapter>
   |  <chapter>
25 |      <title>Maintenance</title>
   |      <para>Be friendly to your printer when you speak to it.</para>
   |      <para>If the green led is blinking, please add paper using the following procedure.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert---d1e56">
   |         <title>Inserting paper into printer</title>
30 |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |         <step xml:id="s1---d1e56">
   |            <para>Make sure that you have paper.</para>
   |         </step>
35 |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1---d1e56"/>
   |            </para>
   |         </step>
   |      </procedure>
40 |  </chapter>
   |</book>

Example B.4 Local linkscope

You can manually assign the value of the suffix used in transcluded content. Example B.5, Manually assigned suffix shows how to do this.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook"
   |      xmlns:xi="http://www.w3.org/2001/XInclude"
   |      xmlns:trans="http://docbook.org/ns/transclude"
 5 |      version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
   |    <title>Buying printer</title>
   |    <para>Grab money, go to shop, ...</para>
10 |  </chapter>
   |  <chapter>
   |    <title>Quick installation guide</title>
   |    <para>Carefully follow all procedures below.</para>
   |    <xi:include href="procedure.001.xml" trans:idfixup="suffix" trans:suffix="_install-proc"/>
15 |  </chapter>
   |  <chapter>
   |    <title>Maintenance</title>
   |    <para>Be friendly to your printer when you speak to it.</para>
   |    <para>If the green led is blinking, please add paper using the following procedure.</para>
20 |    <xi:include href="procedure.001.xml" trans:idfixup="suffix" trans:suffix="_maintain-proc"/>
   |  </chapter>
   |</book>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
 5 |      <title>Buying printer</title>
   |      <para>Grab money, go to shop, ...</para>
   |  </chapter>
   |  <chapter>
   |      <title>Quick installation guide</title>
10 |      <para>Carefully follow all procedures below.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert_install-proc">
   |         <title>Inserting paper into printer</title>
   |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
15 |         <step xml:id="s1_install-proc">
   |            <para>Make sure that you have paper.</para>
   |         </step>
   |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1_install-proc"/>
20 |            </para>
   |         </step>
   |      </procedure>
   |  </chapter>
   |  <chapter>
25 |      <title>Maintenance</title>
   |      <para>Be friendly to your printer when you speak to it.</para>
   |      <para>If the green led is blinking, please add paper using the following procedure.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert_maintain-proc">
   |         <title>Inserting paper into printer</title>
30 |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |         <step xml:id="s1_maintain-proc">
   |            <para>Make sure that you have paper.</para>
   |         </step>
35 |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1_maintain-proc"/>
   |            </para>
   |         </step>
   |      </procedure>
40 |  </chapter>
   |</book>

Example B.5 Manually assigned suffix

By default, XInclude does not do any postprocessing. Thus, the resulting document in Example B.6, Disabling ID fixup contains duplicate IDs and is not valid.

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook"
   |      xmlns:xi="http://www.w3.org/2001/XInclude"
   |      version="5.0">
 5 |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
   |    <title>Buying printer</title>
   |    <para>Grab money, go to shop, ...</para>
   |  </chapter>
10 |  <chapter>
   |    <title>Quick installation guide</title>
   |    <para>Carefully follow all procedures bellow.</para>
   |    <xi:include href="procedure.001.xml"/>
   |  </chapter>
15 |  <chapter>
   |    <title>Maintenance</title>
   |    <para>Be friendly to your printer when you speak to it.</para>
   |    <para>If green led is blinking, please add missing paper using the following procedure.</para>
   |    <xi:include href="procedure.001.xml"/>
20 |  </chapter>
   |</book>

Result of transclusion:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
 5 |      <title>Buying printer</title>
   |      <para>Grab money, go to shop, ...</para>
   |  </chapter>
   |  <chapter>
   |      <title>Quick installation guide</title>
10 |      <para>Carefully follow all procedures bellow.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert">
   |         <title>Inserting paper into printer</title>
   |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
15 |         <step xml:id="s1">
   |            <para>Make sure that you have paper.</para>
   |         </step>
   |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1"/>
20 |            </para>
   |         </step>
   |      </procedure>
   |  </chapter>
   |  <chapter>
25 |      <title>Maintenance</title>
   |      <para>Be friendly to your printer when you speak to it.</para>
   |      <para>If green led is blinking, please add missing paper using the following procedure.</para>
   |      <procedure xml:base="procedure.001.xml" xml:id="paper-insert">
   |         <title>Inserting paper into printer</title>
30 |         <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |         <step xml:id="s1">
   |            <para>Make sure that you have paper.</para>
   |         </step>
35 |         <step>
   |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1"/>
   |            </para>
   |         </step>
   |      </procedure>
40 |  </chapter>
   |</book>

Example B.6 Disabling ID fixup

Suppose we have note in a separate file (note.001.xml):

  |<?xml version="1.0" encoding="UTF-8"?>
  |<note xmlns="http://docbook.org/ns/docbook" xml:id="note">
  |  <para>Important note.</para>
  |</note>

We transclude it into another file (procedure.002.xml) assigning a suffix manually:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<procedure xmlns="http://docbook.org/ns/docbook" xml:id="paper-insert"
   |  xmlns:xi="http://www.w3.org/2001/XInclude"
   |  xmlns:trans="http://docbook.org/ns/transclude">
 5 |  <title>Inserting paper into printer</title>
   |  <para>This procedure is for printer owners.
   |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |  <step xml:id="s1"><para>Make sure that you have paper.</para></step>
   |  <step><para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1"/></para></step>
10 |  <step>
   |    <xi:include href="note.001.xml" trans:idfixup="suffix" trans:suffix="_note001"/>
   |  </step>  
   |</procedure>

Then we transclude this procedure into a master document, again with a manually specified suffix:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook"
   |      xmlns:xi="http://www.w3.org/2001/XInclude"
   |      xmlns:trans="http://docbook.org/ns/transclude"
 5 |      version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
   |    <title>Buying printer</title>
   |    <para>Grab money, go to shop, ...</para>
10 |  </chapter>
   |  <chapter>
   |    <title>Maintenance</title>
   |    <para>Be friendly to your printer when you speak to it.</para>
   |    <para>If the green led is blinking, please add paper using the following procedure.</para>
15 |    <xi:include href="procedure.002.xml" trans:idfixup="suffix" trans:suffix="_procedure002"/>
   |  </chapter>
   |</book>

The result is that the ID in the transcluded note contains a chained suffix note_procedure002_note001:

 1 |<?xml version="1.0" encoding="UTF-8"?>
   |<book xmlns="http://docbook.org/ns/docbook" version="5.0">
   |  <title>Definitive Printer Guide</title>
   |  <chapter xml:id="buy">
 5 |      <title>Buying printer</title>
   |      <para>Grab money, go to shop, ...</para>
   |  </chapter>
   |  <chapter>
   |      <title>Maintenance</title>
10 |      <para>Be friendly to your printer when you speak to it.</para>
   |      <para>If the green led is blinking, please add paper using the following procedure.</para>
   |      <procedure xml:base="procedure.002.xml" xml:id="paper-insert_procedure002">
   |         <title>Inserting paper into printer</title>
   |         <para>This procedure is for printer owners.
15 |    If you don't have a printer, consider <link linkend="buy">buying one</link>.</para>  
   |         <step xml:id="s1_procedure002">
   |            <para>Make sure that you have paper.</para>
   |         </step>
   |         <step>
20 |            <para>Insert paper into printer. If you don't have paper, consult <xref linkend="s1_procedure002"/>
   |            </para>
   |         </step>
   |         <step>
   |            <note xml:base="note.001.xml" xml:id="note_procedure002_note001">
25 |               <para>Important note.</para>
   |            </note>
   |         </step>  
   |      </procedure>
   |  </chapter>
30 |</book>

Example B.7 Chaining suffixes

Appendix C. DocBook schema with support for transclusions

The following customization layer allows transclusion attributes in DocBook. No changes are required for XInclude which already allows arbitrary namespaced attributes.

 1 |namespace rng = "http://relaxng.org/ns/structure/1.0"
   |namespace db = "http://docbook.org/ns/docbook"
   |namespace trans = "http://docbook.org/ns/transclusion"
   |default namespace = "http://docbook.org/ns/docbook"
 5 | 
   |include "docbookxi.rnc" {
   |  db.common.base.attributes |= (db.trans.idfixup? & db.trans.suffix? & db.trans.linkscope?)
   |}
   | 
10 |db.trans.idfixup = attribute trans:idfixup { "none" | "suffix" | "auto" }
   |db.trans.suffix = attribute trans:suffix { text }
   |db.trans.linkscope = attribute trans:linkscope { "user" | "local" | "near" | "global" }

Appendix D. Change log

Revision History

12 May 2021

ndw

Removed the “sample transclusion processor” appendix as it was incomplete and buggy.
Added the sample schema in Appendix C, DocBook schema with support for transclusions.

Bibliography

[XI11] XML Inclusions (XInclude) Version 1.1. W3C Working Group Note. 21 July 2016. Available at https://www.w3.org/TR/xinclude-11/.

For example, XSLT-based implementations can use the generate-id() function to generate a unique suffix.