MEP: More flexible version attribute

= MEP-XXXX
- 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.

[example]
[code]
<revision version="14.04 upstream:3.10" date="2014-04-01"
version="final"/>

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

[example]
[code]
<revision version="user-guide:1.4 admin-guide:1.3 install-guide:1.0"/>

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

[example]
[code]
<revision version="user-guide:1.4" date="2014-06-3" status="outdated"/>
<revision version="admin-guide:1.3" date="2013-06-03" status="review"/>
<revision version="install-guide:1.0" date="2011-06-03" status="final"/>


== 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.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: mep-version.page
Type: text/x-mallard-page+xml
Size: 7898 bytes
Desc: not available
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20141216/efd00932/attachment.bin>