This element 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,
changes, and distributions. A document has a version number of the
form docnumber.docversion-release. 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.
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. You would normally set the version number to be one greater than the previous version.
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'.
Other changes to the document are labelled by a change element. These record an edit of a document without a corresponding change to an version number. I anticipate that the change element could actually cover a range of edits to a document: for example the assorted changes made, perhaps over a period of some weeks, after a beta-release of the document or any associated software.
The distribution and change elements have
an optional versionid attribute. This allows you to specify a
label for this edit. Throughout the rest of the document, you might
insert update elements to comment or document a change or
insertion. These elements have a required versionid attribute
which allows them to refer to a distribution or change element, and
inherit their date and author from them. These updates can be
collected together at the end of a document, and serve as a `what's
new' section for readers of the updated document.
Example:
<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='DR-0.2'>Released to programmers for comment. <change author=ng date='04-MAR-1999' versionid=post-0.2>Various tidyings <version author=mb date='05-MAR-1999' number=1>First public release ... <p><update versionid=post-0.2>Corrected typos and reexpressed argument</update>In this section... <sect>Further details <update versionid=post-0.2>Added this section</update> <p>Blah...
(version ,
(version |
distribution |
change) *
)
history |_(version, |__(version | |___distribution | |___change)*)