Metanorma: Aequitate Verum

Author's documentation

Machine-readable changes

Individual changes to documents can be presented in a machine-readable form in Metanorma.

This form is recommended for use in document amendments, where every independent change (“patch”) are encoded in machine-readable format for extraction. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3]

The machine-readable change format involves expressing each change as a clause. Clauses describing changes are identified through the attribute change, which describes the kind of change involved; the allowed values are:

  • add;

  • modify; and

  • delete.

The following attributes can be expressed on changes:

  • locality gives the location in the reference document to be modified, as a collection of locality key/values, following the convention in localities and locality values.

  • path gives an XPath within the identified locality, indicating the specific element to be changed. * path_end is used in conjunction with path, if a range of elements is to be changed. In that case, path gives the initial element in the range, and path_end gives the final element.

  • title can be used to specify a title for the change. If a title is given for the clause, that is used instead.

The content of the change clause is treated as the human-readable description of the change.

[change=delete,locality="clause=introduction",path="./p[4]",path_end="./p[7]",title="Introduction"]
== {blank}

Delete the fourth to seventh paragraphs.

If the change attribute has the value modify, the replacement text needs to be provided. This is represented as a final blockquote within the change clause.

[change=modify,locality="page=14,clause=4.3.1",title="Array based unstructured mesh",path="./source"]
==== {blank}

_Some attributes referenced in the EXPRESS are not properly defined,
Remove the EXPRESS definition of this entity and replace with:_

____
[%unnumbered]
[source,html]
----
*)
ENTITY array_based_unstructured_mesh
...
(*
----
____

The replacement text may contain assets that need to be numbered on rendering, in order to reflect how they should look in the target document.

Replacement text cannot rely on auto-numbering, and its content is by default skipped in auto-numbering. However, the starting point for any auto-numbering can be defined for an asset with the macro autonumber:asset_class[value], giving the starting value for auto-numbering an asset class within the change clause.

autonumber:table[2] means start numbering any tables in the replacement text from 2. 
[locality="page=27",path="//table[2]",path_end="//table[2]/following-sibling:note[1]"]
==== {blank}

autonumber:table[2]
autonumber:note[7]

_This table contains information on polygon cells which are not
included in ISO 10303-52. Remove table 2 completely and replace
with:_

____
.Edges of triangle and quadrilateral cells
|===
2+^.^h| triangle 2+^.^h| quadrilateral
^.^| edge ^.^| vertices ^.^| edge ^.^| vertices
^.^| 1 ^.^| 1, 2 ^.^| 1 ^.^| 1, 2
^.^| 2 ^.^| 2, 3 ^.^| 2 ^.^| 2, 3
^.^| 3 ^.^| 3, 1 ^.^| 3 ^.^| 3, 4
| | ^.^| 4 ^.^| 4, 1
|===

NOTE: This is not generalised further.
____

If the starting value is empty, the asset is treated as unnumbered:

[change=replace,locality="clause=4.2.2,note=1"]
== 4.2.2
autonumber:note[]
Replace "`NOTE`" with the following:
[quote]
____
[NOTE]
The calendar year used in the week calendar...
____

Corrigenda

Text to be marked as added or deleted in corrigenda is indicated through the commands add:[…​] and del:[…​] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.0]:

del:[The use of echo cancellers on the VBD channel, as per Rec. ITU-T G.168.]

... or other forms of redundancy add:[(e.g. per <<rfc2198>>)]

For more complicated corrigenda involving changes, you may use reviewer notes.