1.8. Incorporating External Files in Code Listings

1.8. Incorporating External Files in Code Listings
Prev	Chapter 1. Knowing DocBook’s Structure	Next

Difficulty: ★☆☆ (easy)

Keywords: programlistings, code, XInclude, textdata, DocBook extensions

Problem

You have external files (codes, example files, and others) that you want to incorporate into a programlisting element, but you want to keep your files separate from your documentation files.

Solution

Use one of the following methods to incorporate external files into your programlisting element:

textobject/textdata
xi:include (XIncludes)

You can mix both, but for consistency reasons, it is better to stick to one method.

Incorporating External Files with `textdata`

Usually, textdata is included inside a textobject that is then included inside a programlisting element.

To refer to a file foo.py with textdata, use the code in Example 1.9, “External File Marked-Up With textdata”.

Example 1.9. External File Marked-Up With textdata

<programlisting><textobject>
   <textdata fileref="foo.py"/>
</textobject></programlisting>

Incorporating External Files with XIncludes

The same code in Example 1.9, “External File Marked-Up With textdata” can be expressed with XInclude:

Example 1.10. External File Marked-Up With xi:include

<programlisting><xi:include
  href="foo.py" parse="text"
/><programlisting>

Do not forget to declare the namespace URI http://www.w3.org/2001/XInclude. This can be done either on the xi:include element itself, or in the root element of your documentation. Preferably, it is easier to declare it once inside the root element.

Discussion

Keeping your external files separate from your documentation can have several reasons. Probably you need to change the files very often or you do not have control over these files. In such cases, it is better to leave them as separate files and don't include them directly into your XML code. Otherwise it would be tedious to include them manually whenever your code changes.

To avoid such tedious tasks, the textdata and xi:include elements were invented. The element textdata was introduced in DocBook 4.2, released in 2002. At that time the XInclude specification was not written yet, the first public release was published in 2006. Too late for DocBook to incorporate it into its schema.

Nowadays, in the light of XInclude, the element textdata can be considered obsolete—especially for DocBook 5 documents. Therefore, for new documents, prefer the XInclude element(s) as this has more advantages (see Table 1.3, “Comparision Between textdata and xi:include”).

Table 1.3. Comparision Between textdata and xi:include

Topic	`textdata`	`xi:include`
Needs DocBook extension?	Yes	No
Can be used elsewhere in the document?	No	Yes
Can include text?	Yes	Yes
Can include XML markup?	No	Yes
Can use fallback mechanism?	No	Yes
Included in DocBook 4?	Yes	No^[a]
Included in DocBook 5?	Yes	Yes^[b]
^[a]Not included in the DTD, but can be used anyway. ^[b]Only available in the separate files `docbookxi.rn{c,g}`

If you still want (or have) to use textdata you need to transform your DocBook documents with Saxon or Xalan. Currently, the extension functions are only available for these XSLT processors, not xsltproc. Make sure the DocBook extension JAR file(s) are included in your CLASSPATH variable. Furthermore, set the parameters use.extensions and textinsert.extension to 1 to enable this functionality.

Prev	Up	Next
1.7. Incorporating Code Listings	Home	1.9. Inserting Remarks