More flexible version attribute

This page proposes an extended form for the version attribute of the informational revision element. It allows an arbitrary number of versions for different products, documents, or other resources. It also proposes deprecating the docversion and pkgversion attributes.

Background

Mallard 1.0 provides for three types of version numbers to be recorded for each revision of a page or section:

version: The version of the page, or the overall version if no separate resources are used.

docversion: The version of the document containing the page. Documents contain multiple pages.

pkgversion: For shipped packages, the version of the package containing the document. Packages may contain multiple documents, and the package version may correspond to the version of an application.

In actual practice, this trichotomy is seldom used, and it fails to address real-world needs for multiple version numbers. In particular, it doesn't account for the case where individual pages are included in multiple documents. This is important in two common use cases:

If Project B is a fork or downstream of Project A, it may reuse some pages, and periodically sync pages from Project A, possibly applying minor patches in the process. In this case, it is useful for Project B to know which version of Project A pages are taken from, or if the pages are original to Project B.

A team may make multiple products with common components, such as configuration systems or user interface elements. Or, a team may make multiple documents for a single product, each aimed at a different audience. In either case, common practice is to have a common content pool of pages that multiple documents can use. In this case, it is useful to know against which versions of each product or document the pages have been reviewed.

Proposal

This page proposes allowing the version attribute of the informational revision take a space-separated list of version token. A version token may be a bare version number, or it may be a colon-separated pair consisting of a version key on the left and a version number on the right.

This can be taken as a mapping from strings to version numbers, with a bare version number being the value for the empty string. (This would make a bare version number equivalent to preceding a version number with a colon with no text before it.) It's useful to be able to get exactly one version number for a version key, so if a version number is specified multiple times for a version key, the last one is used.

Since this system can easily encapsulate the extra information from the docversion and pkgversion attributes, usage of those attributes would be deprecated, though they would remain in the schema for compatibility reasons. To allow new tools to work with all statuses in the same way, if the docversion or pkgversion attributes are used, then those version numbers are prepended to the version list with the doc and pkg version keys, respectively.

Examples

Record a version number along with the version of an upstream project the page was last synced with.

]]>

Record the version of multiple documents, indicating the last time a page was reviewed in the context of each document.

]]>

Alternatively, use multiple revision elements, each with a keyed version, to record separate status information for the page in each document.

]]>

Compatibility and Fallback

This proposal has one potential backwards incompatibility. Because the colon character will be used to separate version keys from version numbers, any page which uses colons in version numbers will not be interpreted the same way by a processing tool that implements this proposal. Although this is valid, it is uncommon.

This proposal deprecates two attributes, but provides an automated upgrade path for pages using those attributes.

The fallback behavior for multiple version tokens in one attribute is not ideal. Any tool that does not implement this proposal will treat the entire attribute value as a single version number. Authors who need to use these tools should instead use multiple revision elements, each with only one version token.

Comparison to Other Formats

The DocBook revision element can contain at most one revnumber element. There are no restrictions on the content of the revnumber element, so a similar system to this proposal could be used without any validity problems. Without a formal recommendation, however, it is unlikely that revision-tracking tools will produce the desired result. Another potential way to specify versions of multiple products is to have multiple revhistory elements, one for each product, using distinct id attributes or title elements.

The DITA vrmlist element allows you to specify versions of a product to which a topic applies. The vrmlist element is contained by the prodinfo element, and you can have multiple prodinfo elements for a single topic. To specify versions of different products, you can have multiple prodinfo elements, one for each product, using distinct id attributes or prodname elements.