Author’s documentation

Reviewer notes and comments

General

A Metanorma AsciiDoc document can be annotated with reviewer notes (or comments, essentially, arbitrary blocks of text).

Sidebars can be separated at a distance from the text they are annotating; the text they are annotating is indicated through anchors. Its syntax aligns with AsciiDoc sidebar notation.

Note

Reviewer notes are only rendered if :draft: attribute has been specified for the document(s).

Reviewer comments

The following attributes on reviewer comments are mandatory:

  • reviewer attribute (naming the reviewer)

  • the starting target anchor of the note (from attribute)

The following attributes are optional:

  • date attribute, optionally including the time (as xs:date or xs:datetime)

  • the ending target anchor of the note (to attribute)

The span of text covered by the reviewer note is from the start of the text encompassed by the from element, to the end of the text encompassed by the to element. If only the from element supplied, the reviewer note covers the from element. The from and to elements can be bookmarks, which cover no space.

EXAMPLE:

=== Address Profile Definition (AddressProfileDescription)

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

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

which renders

Illustration of a reviewer comment covering a span of text
Figure 1. Illustration of a reviewer comment covering a span of text. (the :draft: attribute needs to be set in the document in order to render any reviewer notes.)

TODO expressions

A commonplace convention in software source code, as well as lightly marked up text, is to prefix comments indicating pending actions with TODO. Metanorma treats TODO as an admonition label, and converts it into a reviewer note.

The from, to reviewer and date attributes are all treated as optional.

EXAMPLE:

TODO: This is treated as a Reviewer note.

[TODO]
====
This is also treated as a Reviewer note
====