Metanorma: Aequitate Verum

Adding comments

You can annotate a Metanorma AsciiDoc document with comments and `TODO`s to indicate a pending action.

Note

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

Reviewer comments

To create a comment:

  1. Define the start of the comment by creating an anchor [[start]].

  2. Define where the comment should end by creating an anchor [[end]] (optional).

  3. Add the comments metadata: [reviewer="Your Name",date=YYYYMMDDT0000,from=start,to=end]
    The date and to attributes are optional. The timestamp in the date attribute is optional, too. The from and to elements can be bookmarks which cover no space.

  4. Begin the comment block using four asterisks ****.

  5. Enter your comment.

  6. Close the comment block with four asterisks ****.

Example of a comment
=== Address Profile Definition (AddressProfileDescription)

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

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 of a TODO
TODO: This is treated as a reviewer note.

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

Practice time

The code for this exercise is available on GitHub.

The corresponding file is named exercise-3-1.adoc

The text contains some typos. Mark the errors using comments.

  • Line 25: commnuity

  • Line 27: agencys

  • Line 20: colaborative

Now that we’ve commented on the content, let’s create a draft of the document.