Chapter 29. Revision control

Table of Contents

Revision elements and attributes
Formatting revhistory
XSL-FO output for revhistory
HTML output for revhistory
Draft mode
Using the status attribute
Profiling on status
Highlighting status
Highlighting changes
Change markup
HTML change output
XSL-FO change output

DocBook is often used in situations where content is published periodically or on a continuous basis, with revisions and updates incorporated into each new release. It is often necessary to keep track of changes and be able to identify changed documents or elements, for reasons such as:

The DocBook DTD provides several elements and attributes that are useful for tracking changes, and the DocBook XSL stylesheets provides support for rendering those elements and attributes in useful ways for readers. These tools can be used in conjunction with revision control software that stores multiple versions of a document.

Revision elements and attributes

The following is a summary of the elements and attributes that can be used to record changes and release information for documents and elements.

Table 29.1. Revision elements and attributes

revhistoryElementContains a record of changes for an element, each change recorded in a revision element. It can appear at many document levels inside any of the info elements, as well as in qandaentry and glossentry.
revisionElementRecords a single change in a revhistory, using a revision number, date, and description.
releaseinfoElementTypically used to indicate a version number or name for a released document. Can be used in any of the info elements.
editionElementTypically used to indicate a document edition number.
pubdateElementTypically used to indicate a publication release date.
printhistoryElementCan contain a sequence of para elements describing a publication history.
revisionflagAttributeCan be used to indicate that the element has changed. This common attribute is available on all elements, with enumerated values added, deleted, changed, or off.
revisionAttributeCan be used to indicate revision information on an element. This common attribute is available on all elements, and can take any text value.
statusAttributeCan be used to indicate the status of an element, such as its current production status. Available on all division and component elements, and can take any text value.

If you want to record the history of revisions in a document, you can use the revhistory element which contains a sequence of revision elements to record each change. The stylesheets do not output revhistory by default, but it can be output as described in the section “Formatting revhistory”.

The releaseinfo, edition, and pubdate elements are usually updated just prior to publication to identify a particular release of a document. They are typically printed on a title page, if at all. See Chapter 11, Title page customization.

The three attributes revisionflag, revision, and status can be used to track changes at the level of each element. The revisionflag element can indicate only that an element has changed, while revision can take any text value to describe a revision.


If you use a content management system such as CVS, you can store revision keywords in a revision attribute in your document. The keywords will be expanded during checkout, so the attribute will contain the latest CVS information for the document. For example:

Enter a revision attribute:
<article revision="$Id: dbxsl.xml,v 1.128 2007/09/02 18:19:18 bobs Exp $">

After checkout:
<article revision="$Id: dbxsl.xml,v 1.128 2007/09/02 18:19:18 bobs Exp $">

If you manually enter revisionflag attributes, keep in mind that they can quickly become out of date. For example, a section marked as added in one release should not be so marked for the following release, or even the next review cycle. After a release or review, you may need to go back and clear all revisionflag attributes to start the next cycle. The revisionflag attribute is most useful when it is generated in a temporary document created by comparing two versions. See the section “Highlighting changes” for more information.

The status attribute only appears on elements that make up the hierarchy of a document, and is typically used for tracking the production status such as draft, edited, final, etc. It can take any text value, so you might want to decide on a few enumerated values for your authors to use in order to maintain consistency. You can use status in profiling to select content for output, or add a customization to highlight elements with different status using color or some other effect. See the section “Using the status attribute” for more information.