Revision Status Flags
This page proposes extending the status attribute of the informational revision element to allow a space-separated list of status flags. The first flag in the list would serve as the primary status, equivalent to the current single-value status. Further status flags could provide additional information.
This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on.
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 , for example, uses a custom set of statuses.)
Seefor a proposal on changing how version numbers are recorded for revisions.
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:
Secondary version tokens should be written as colon-separated pairs, similar to the syntax for, , and . 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 .
Status flags can be used for other purposes as well.
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.proposes extending the
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 . 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, 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 , 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.
Compatibility and Fallback
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.
Comparison to Other Formats
This section is not yet written. Discuss this proposal on.