Element to Record Reviews

This page proposes adding a new informational element review to the Mallard core, as a child element of the revision element.

Authors: Shaun McCance
Created: 2019-12-07
Status: proposed (2019-12-07)
Target: 1.2
show history
hide history
2019-12-07 1.2 proposed

This proposal is still under consideration. Revisions may still be made based on your input. Discuss this proposal on mallard-list.


Mallard provides the revision element to record information about the current revision, including multiple version numbers, the date, and the status. While you can use the revision element to mark a page as needing reviews, there is no standard way to record those reviews when they happen.


This page proposes adding a new review element as a child element of the informational revision element. Each revision element could have any number of review elements, with each review element recording one review done against that revision.

Each review element can optionally contain each of the following attributes:


The type of review being performed, such as a peer review, technical review, or final review. Any value would be allowed, but we should make recommendations for common values. These values should be coordinated with review status flags in MEP-0021: Revision Status Flags. Possible values include gap, markup, draft, devel, tech, style, legal, copy, and final.


The status as reported by the reviewer. This might indicate that the page is ok, or that it needs work. Any value would be allowed, but we should make recommendations for common values.


An identifier for the person doing the review. This could be an email address or just a username. This is different from how the comment element uses the cite element to record the name of the person. We may consider the by attribute in other places, such as comment and revision.


The date the review was done, preferably in the One True Date Format.


A URL where the full text of the review can be found.

Additionally, the review element can optionally contain any general block content. This can be used to write the review directly in the page.


This section is not yet written. Discuss this proposal on mallard-list.


Since reviews are internal notes amongst teams, translating them is likely not the best use of time. Translation tools should consider making the block content of a review element untranslatable by default.

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 for a new info element is that is is ignored. The review element is not intended to be displayed to users in normal circumstances, so there is no loss of functionality when using older tools that do not support this proposal.

Comparison to Other Formats

Although both DocBook and DITA provide mechanisms for recording revisions and status information, neither provides a comparable mechanism for recording reviews. This is usually left to external systems.

© 2019 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by