Chapter 29. Revision control

Chapter 29. Revision control
	Part IV. Special DocBook features

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:

You want to be able to produce multiple states of a document, such as the most recently released version and the current draft version under development, from the same source files.
Reviewers only want to review what has changed, not an entire document.
You want to be able to print a list in a preface or appendix what has changed in the current version.
The documents are translated into other languages, and you only want to pay for retranslation of content that has changed.

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

Name	Type	Description
`revhistory`	Element	Contains 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`.
`revision`	Element	Records a single change in a `revhistory`, using a revision number, date, and description.
`releaseinfo`	Element	Typically used to indicate a version number or name for a released document. Can be used in any of the `info` elements.
`edition`	Element	Typically used to indicate a document edition number.
`pubdate`	Element	Typically used to indicate a publication release date.
`printhistory`	Element	Can contain a sequence of `para` elements describing a publication history.
`revisionflag`	Attribute	Can 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`.
`revision`	Attribute	Can be used to indicate revision information on an element. This common attribute is available on all elements, and can take any text value.
`status`	Attribute	Can 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.

Tip

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.


Q and A in table of contents		Formatting revhistory