Next / Previous / Contents / Shipman's homepage

1. DocBook section IDs need an index

This document describes a tool for people who write documents using the DocBook system. Here at the New Mexico Tech Computer Center, the guide for DocBook authors is Writing documentation with DocBook-XML 4.3.

Each section element in a DocBook document must carry an id attribute. Here is an example.

<section id='intro'>
  <title>Introduction</title>
  ...

The DocBook xref element is used to cross-reference other locations within the same document. In general, this element looks like this:

<xref linkend='T' />

The value T of the linkend attribute names the id attribute of the cross-referenced section. So, for example, to refer to the “Introduction” shown above, you would say something like this:

  See <xref linkend='intro'/> for more information.

Once you start writing sizeable documents, it can become hard to remember the id values for each section. It helps to have some kind of convention, but even so, there can be a lot of id values in a document.

The docbookindex application is a program that reads your DocBook .xml file and generates a report, in PDF format, showing all the section id values, in an outline format.

As an example, here is the PDF of the index for the document you are now reading.