Table of Contents
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.
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
|Element||Contains a record of changes for an element, each change recorded in a |
|Element||Records a single change in a |
|Element||Typically used to indicate a version number or name for a released document. Can be used in any of the |
|Element||Typically used to indicate a document edition number.|
|Element||Typically used to indicate a publication release date.|
|Element||Can contain a sequence of |
|Attribute||Can be used to indicate that the element has changed. This common attribute is available on all elements, with enumerated values |
|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.|
|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”.
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
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.
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.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises