Includes change, distribution, docdate, history, update, version.
In a large document which will be revised in future, it is important to preserve some document history. This means that readers can check which version of a document they are reading, and find what parts of it have changed since the last version they are familiar with.
The history element, within in the docinfo element (see Section 4.1), records the history of the document. It is available in most of the Starlink DTDs, but not all, and when it is omitted, the docdate element is required instead.
The history of a document is composed of a sequence of versions,
distributions and changes. A document has a version number of the
form docnumber.docversion-distribution. The document number is the
number declared in the docnumber
element, as assigned by the Starlink librarian. The document version
indicates which edit of the document this is - a significant update
to the document should be marked by incrementing the document version
number. The release information marks a more minor update to a
document.
All dates within these elements have the format dd-mmm-yyyy,
where dd indicates a two-digit day number, mmm a
three-letter month name (such as jan, feb and so on, in
any mixture of case), and yyyy a four-digit year number. Let's
keep things Gregorian - no Julian, French-revolutionary or Mayan
dates, if you would be so kind.
Each of the three elements has paragraph content, to record brief notes about the change or distribution.
A version of a document (marked by a version element in the history) is a significant release of a document, perhaps describing new functionality in a package. The number attribute gives the version number to be attached to the document.
A distribution of a document (marked by a
distribution element in the history) is
a less significant update to a document, perhaps for distribution to
readers for comments. The string attribute is a label for the
distribution, and could be something like `draft1' or `comments-13',
or `DR-0.7-8'.
Other changes to the document are labelled by a change element. These record an edit of a document without a corresponding change to a version number.
The distribution and
change elements have an optional
versionid attribute. This allows you to specify a label for
this edit. Any update elements
elsewhere in the text must attach themselves to one of these elements,
using the versionid attribute.
For example:
Presumably, the `comm-0.1' release of the document elicited some comments, and the resulting changes have been logged by the change element immediately following it. Any (optional) update elements scattered throughout the document (they can be children of the list structures, figures, tables, paragraphs, and the document body itself) can link back to this element to inherit its authorship and date. These updates could be collected together by an application, to generate a change log, or a `new in this release' section.<author id=ng>Norman <editors> <author id=mb>Martin ... <history> <version author=ng date='02-MAR-1999' number=0>Initial version <distribution author=ng date='03-MAR-1999' string='comm-0.1'>Released to programmers for comment. <change author=ng date='04-MAR-1999' versionid=post-0.1>Various tidyings <version author=mb date='05-MAR-1999' number=1>First public release ... <p><update versionid=post-0.1>Corrected typos and reexpressed argument</update>In this section....