MEP-0021

Mallard provides informational revision elements that allow you to provide certain information about a revision: the version number of that revision, what version of a containing document or package it belongs to, what date the revision was made, and what the status of that revision is. There is a recommended list of statuses, although you can use any status marker you like. (The MEP process, for example, uses a custom set of statuses.)

One limitation of the status attribute is that it is only expected to contain a single value. It is often useful to specify additional status information about a revision. For example, you can set the status attribute to "review" to specify that a revision needs to be reviewed, but there is no standard way to specify how many reviews it needs, what kinds of reviews it needs, or who needs to perform those reviews.

This page proposes extending the status attribute to allow a space-separated list of status tokens, using the xsd:NMTOKENS production. The first value in this list is the primary status, which serves the same role as the current single-value status. Further values would provide additional information.

A tool that just lists a single status for a page could be minimally adapted to this proposal by just taking the first value. For example, using the EXSLT str:split function:

str:split(@status)[0]

Secondary version tokens should be written as colon-separated pairs, similar to the syntax for conditional tokens, the proposed tags element, and the proposed extension to the version attribute. The actual values are arbitrary and can be made up to support the needs of particular projects or documents. A recommended syntax and set of flags encourages consistency and makes things easier to remember.

As an example, if a document needs to be reviewed, its status is set to "review". However, this doesn't indicate what type of review is needed. More information could be provided using additional status flags. If a document needs both a technical review and a legal review, its status could be set to "review review:tech review:legal".

As a special convenience, if the status list starts with a value with the prefix "review:", the primary status is implicitly just "review", and all of the explicit status flags are secondary.

The review types in status flags should match those used in the type attribute of the rewiew element, as proposed in MEP-0019: Element to Record Reviews.

Status flags can be used for other purposes as well.

MEP-0006: More Flexible version Attribute proposes extending the version attribute to allow different version numbers for different component, distributions, or vendors. This proposal could also allow specifying different statuses for those. For example, the vendor Fez might use the status flag "fez:final" to indicate that they have approved the page for their product.

Furthermore, this proposal could be used to indicate what a page needs. For example, a project might decide that all of its pages should have a keywords element, which was added in Mallard 1.1. Pages without a keywords element could be marked with the "needs:keywords" status flag.

These are all just examples of how status flags could be used. The specification should allow arbitrary use and ad hoc prefixes. However, we should also make recommendations to encourage consistency.

Indicate that a page needs reviews for technical accuracy and for style:

<revision version="1.2" date="2020-10-31"
          status="review review:tech review:style"/>

@revision[version=1.2 date=2020-10-31
          status="review review:tech review:style"]

Combined with multiple version tokens from MEP-0006: More Flexible version Attribute, use a status flag to show that a vendor has signed off on a release:

<revision version="1.2 fez:33" date="2020-10-31"
          status="final fez:final"/>

@revision[version="1.2 fez:33" date=2020-10-31
          status="final fez:final"]

Use status flags to indicate a page needs keywords and desc elements:

<revision version="1.2" date="2020-10-31"
          status="review needs:keywords needs:desc"/>

@revision[version=1.2 date=2020-10-31
          status="review needs:keywords needs:desc"]

Status flags with the needs: prefix can use arbitrary values, not simply element names. With MEP-0008: Multiple desc Elements, use a status flag to indicate the a page needs a special desc element with the role "topic".

<revision version="1.2" date="2020-10-31"
          status="review needs:desc-topic"/>

@revision[version=1.2 date=2020-10-31
          status="review needs:desc-topic"]

As with the current status attribute, status flags are intended to be tokens from an ad hoc but controlled vocabulary. They should not be marked for translation by localization tools. However, tools that present status information to users may use localized strings to indicate known values of status flags. In such cases, these tools would need to add more localization options.

We considered using a separate flags attribute for the secondary status flags. This approach would have considerably better fallback behavior for older tools. However, we felt that a single space-separated attribute was a better writer experience. Since the poor fallback behavior likely only affect internal tracking, and rarely user-visible publishing, we felt it was worth the poor fallback behavior.

This proposal makes no backwards-incompatible changes. Any page written in a version prior to the implementation of this proposal will work exactly the same in a processing tool that implements this proposal.

The fallback behavior of this proposal is somewhat poor. Any unsupporting tool will consider the entire status attribute to be a single status. This means that tools checking for a specific status may fail to recognize that status when in a space-separated list.