Metanorma: Aequitate Verum

Author's documentation

Annotations (editor notes, reviewer notes, to-dos)

Introduction

Consensus building is vital to any standards development process. For international or industry standards, the internal circulation and public review stages are key to demonstrate consensus and gain public acceptance.

During these review stages, reviewers are asked to provide feedback on the standard draft. Instead of providing a plain draft, standard bodies, authors and editors may opt to provide additional information inline to the draft being reviewed, including review notes, guidance and annotations to clarify the intent of content.

Metanorma provides annotation capability and allows the standards body, and/or the standard’s author or editor, to encode annotations in support for the draft circulation process.

Annotations in Metanorma are rendered across all general output formats, including:

  • HTML

  • PDF

  • Word DOC format

Types of annotations

Metanorma supports the following types of annotation mechanisms, including:

  • Editor notes: notes from the editor (or the editorial process) intended for the reader

  • Reviewer notes: notes and comments from reviewers, internal or external, intended to highlight or clarify issues. Reviewer comments can apply in two ways:

    • Standalone comments: where the comments apply to a particular point in the text.

    • Ranged comments: where comments apply to a range of text, with a defined start and end.

  • To-dos (also "TODOs"): notes intended for the project’s authors or editors as a reminder for a pending action in content.

Editor’s notes

Editor’s notes are specified using the EDITOR: prefix or the [EDITOR] block syntax.

The editor’s note is rendered as a document element (an admonition), which means that they are rendered as real elements in the content flow, and cannot span or point to content. No locality needs to be provided.

The editor’s note is always rendered, regardless of the draft status of the standard.

Example 1. Example of an editorial note (from ISO 19135)
== Conformance

EDITOR: The contents of this clause will be changed in conjunction with the UML.

renders as:

Editor’s note from ISO 19135 (Preview)
Figure 1. Editor’s note from ISO 19135 (Preview)

To-dos

To-dos (or "TODOs" in the computer world) are specified using the TODO: prefix or the [TODO] block.

Similar to the editor’s notes, they are rendered as document elements (as admonitions) and are presented in the content flow. Again, no locality needs to be supplied to use to-dos.

To-dos are only rendered if the :draft: document attribute has been specified for the document(s).

Note
 Similar to reviewer notes, to-do annotations are only rendered if the standard specifies the document attribute :draft:.
Example 2. Example of a TODO (from ISO 19135)
== Introduction

TODO: Revise introduction.

renders as:

To-do from ISO 19135 (Preview)
Figure 2. To-do from ISO 19135 (Preview)

The block syntax of [TODO] is also supported.

Example 3. Example of TODOs in block syntax
[TODO]
--
This is treated as a reviewer note.
--

[TODO]
====
This is also treated as a reviewer note.
====

The from, to reviewer and date attributes are optional and may be specified.

Reviewer notes

General

Reviewer notes are specified using the [reviewer] block syntax. There are two types of reviewer notes:

  • standalone comment

  • ranged comment

The :draft: document attribute must to specified in the document in order to render any reviewer notes.

Note
 The requirement to specify the :draft: attribute is similar to that of to-dos.

The basic syntax of a reviewer note is as follows:

[reviewer={name of reviewer}{optional attributes}]
****
Note content
****

Where:

  • The reviewer note block is wrapped by four asterisks: ****.

  • {name of reviewer} is the name of the reviewer. The reviewer attribute is mandatory.

  • Note content is the intended content of the note.

  • {optional attributes} may contain additional attributes, including:

    • date (optional) to specify the timestamp of the note. The value shall be in the ISO 8601-1 YYYY-MM-DD format. The date attribute is optional.

    • from (optional for standalone, required for ranged) is the anchor location of where the reviewer note should appear (standalone) or start (ranged).

    • to (optional for standalone, required for ranged) is the anchor location of where the reviewer note should appear (standalone) or end (ranged). In the case of a standalone note, either do not specify a to, or ensure that the to is set to the same anchor as the from.

    • type is a classification of the reviewer note, which may be used in downstream processing [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.1].

Standalone reviewer note

Syntax

For a standalone comment, the syntax is as follows:

[reviewer={name of reviewer},date={YYYY-MM-DD}]
****
Note content
****

or

[reviewer={name of reviewer},date={YYYY-MM-DD},from={anchor}]
****
Note content
****

Where:

  • {name of reviewer} is the name of the reviewer

  • {YYYY-MM-DD} is the date of the review comment, in the ISO 8601-1 format "YYYY-MM-DD". The date attribute is optional.

  • Note content is the intended content of the note.

  • {anchor} (optional) is an anchor location of where the reviewer note should appear. This parameter is entirely optional.

Rendering

A standalone reviewer note is rendered in a generated PDF document with:

  • small orange icon with a tool-tip

  • comment text in the Acrobat Reader Comment tool panel

Example

The following block specifies is a standalone reviewer note — as it does not reference a location that relates to concrete text. It is shown at the end of the specified section of from and to.

Example 4. Example of a standalone review note (from the ISO Rice document)
[reviewer=ISO,date=2017-01-01,from=foreword]
****
A Foreword shall appear in each document. The generic text is shown here. It
does not contain requirements, recommendations or permissions.

For further information on the Foreword, see
*ISO/IEC Directives, Part 2, 2016, Clause 12*.
****

renders as:

Standalone reviewer note from the ISO Rice document (Adobe Reader)
Figure 3. Standalone reviewer note from the ISO Rice document (Adobe Reader)
Note
 This example applies bolding to the "ISO/IEC …​, Clause 12" text. Usage of rich-text comments are not supported by all PDF readers, please refer to PDF reader compatibility for details.

Ranged reviewer note

Syntax

For a ranged reviewer note, the syntax is as follows

[reviewer={name of reviewer},date={YYYY-MM-DD},from={from anchor},to={to anchor}]
****
Note content
****

Where:

  • {name of reviewer} is the name of the reviewer

  • {YYYY-MM-DD} is the date of the review comment, in the ISO 8601-1 format "YYYY-MM-DD". The date attribute is optional.

  • Note content is the intended content of the note.

  • {from anchor} is an anchor location of where the reviewer note should start.

  • {to anchor} is an anchor location of where the reviewer note should end.

Rendering

The ranged reviewer note renders as following:

  • small orange icon with a tool-tip

  • highlighted text

  • comment’s text in the Acrobat Reader Comment tool panel

Example

The following example applies a reviewer note that highlights a textual range, namely, the text wrapped by the [[start_review1]] and [[end_review1]] anchors. The reviewer note specifies from=start_review1,to=end_review1 as the start and end.

Example 5. Example of a ranged reviewer comment (from the ISO Rice document)
This second edition cancels and replaces the
[[start_review1]]second[[end_review1]] edition (ISO
{docnumber}-{partnumber}:2009), which has been technically revised.
...

[reviewer=ISO,date=2022-07-01,from=start_review1,to=end_review1]
****
Instead of _second_ should be _first_.
****

renders as:

Ranged reviewer note from the ISO Rice document (Adobe Reader)
Figure 4. Ranged reviewer note from the ISO Rice document (Adobe Reader)
Note
 This example applies italics to the "second" and "first" texts. Usage of rich-text comments are not supported by all PDF readers, please refer to PDF reader compatibility for details.
Example 6. Example of a ranged reviewer comment (from ISO 19160-6)
=== Address Profile Definition (AddressProfileDescription)

This is a clause address [[A]]proflie[[B]] definition

[reviewer="Nick Nicholas",date=20180125T0121,from=A,to=B]
****
proflie?!
****

renders as:

Illustration of a reviewer comment covering a span of text
Figure 5. Illustration of a reviewer comment covering a span of text (Word)

Comparison of annotation methods

Here’s a handy table that compares the differences between the semantic annotation types.

Table 1. Comparison of annotation methods
Annotation type When rendered Supports range?

Editor’s notes

Always

No

To-dos

Only when :draft: is specified

No

Standalone reviewer note

Only when :draft: is specified

No

Ranged reviewer note

Only when :draft: is specified

Yes

PDF reader compatibility

While the PDF standard is widely adopted, not all PDF readers implement all the features available. As it is to be expected, only Adobe Reader (and Adobe Acrobat Pro) attempts to implement all available features.

In the department of PDF annotations:

  • most of the common PDF readers implement plain text comments only

  • the presentation of comments vary widely, and can occasionally crash documents or trigger editing of the comments, and is not always saveable (Preview).

When using reviewer notes, you need to be aware that rich-text functionality such as bold and italics within the notes will lead to those notes being hidden (or broken) in PDF readers that do not implement them.

The following table describes the level of annotation support of common PDF readers.

Table 2. Compatibility of PDF comments across popular PDF readers
PDF viewer application Comments support Rich text support

Adobe Reader

✅

✅

Foxit PDF Reader

✅

doesn’t display rich text from the generated PDF, but text can be formatted as rich text

Preview (macOS)

✅

❌, text displays as plain text only

Skim (macOS)

✅

❌, text displays as plain text only

Firefox (browser)

✅

doesn’t display bolded text, only italic

Safari (browser)

shows only orange icon

doesn’t display text at all

Microsoft Word

❌

❌

Conclusion

Metanorma provides multiple methods for semantically annotating standards, and now this functionality is available across all output formats, including HTML, Word, and PDF.

When using rich-text annotations, consider the PDF reader compatibility matrix in PDF reader compatibility for the intended audience.

Bibliography