Version Information

This is a draft specification. It is likely that changes will still be made before the final specification.

Use the revision information to record information about revisions of a document, page, or section. The revision element allows you to specify version numbers, the revision date, and the revision status. Other information can be recorded with attributes or elements from external namespaces. Multiple revision elements can be used to record the revision history.

You can use the title and desc elements in a revision element to provide a title and description of that revision. This is not necessarily the same as the title and description of the page or section as of that revision.

Notes

The revision element contains an optional title element, an optional desc element, and any number of elements from external namespaces.
The revision element can occur in any info element.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The version attribute records the version number of the page or section.
The docversion attribute can be used to record the version number of the enclosing document.
The pkgversion attribute can be used to record the version number of the package containing this document.
The date attribute records the date this revision was made.

The status attribute records the status of the page or section as of the given revision. The following values are recommended:

"stub"	contains little to no real content
"incomplete"	outline of all information, but lacking content
"draft"	all content available, but unpolished
"outdated"	was once complete or nearly complete, but needs to be revised to reflect changes
"review"	ready to be reviewed by editors
"candidate"	reviewed and awaiting a final approval
"final"	approved and ready for publication or distribution

The revision element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Specify the date that a page was marked ready for review, targeting the 1.0 version of the containing document:

<revision docversion="1.0" date="2011-03-08" status="review"/>

Specify that version 3.0 of a page is still correct for version 3.2 of the package it describes:

<revision pkgversion="3.1" version="3.0" date="2011-03-08" status="final"/>

Processing Expectations

As an informational element, the revision element is not necessarily displayed directly on the page or section in which it appears. Some tools may show revision information on a separate informational page or dialog. Tools designed for editors might show revision information directly.

When a revision element is displayed or processed, tools should process only those child elements that they understand, and ignore everything else.

Comparison to Other Formats

The revision element is similar to the revision element in DocBook. In DocBook, revision elements must occur inside a revhistory element. In Mallard, they are placed directly in an info element. DocBook provides more specific child elements for structured content, as well as for block content for detailed remarks. Mallard allows such information to be encoded with elements from external namespaces when needed.

DITA provides the created and revised elements to specify revisions, which allow fixed attributes to specify dates for creation, modification, deployment, and expiration. In Mallard, revision tags can use the status attribute to provide this information. DITA also provides the vrmlist element to connect a version of the topic to versions of the product. Use the pkgversion attribute in Mallard.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the revision element. The namespace declarations for this definition are on the page Pages.

mal_info_revision = element revision {
  mal_info_revision_attr,
  mal_block_title ?,
  mal_block_desc ?,
  mal_info_revision_content *
}
mal_info_revision_attr = (
  attribute style { xsd:NMTOKENS } ?,
  attribute version { text } ?,
  attribute docversion { text } ?,
  attribute pkgversion { text } ?,
  attribute date { xsd:date } ?,
  attribute status { xsd:NMTOKEN } ?,
  mal_attr_external *
)
mal_info_revision_content = mal_external