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 (commonly called a “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

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

position

the position of an add insertion. Only applies to add clauses, and indicates whether the additional text is to be inserted before or after the locality [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.3.0]. Allowed values are:

before: Before the specified position.
after: After the specified position.

path

the XPath within the identified locality. This value indicates the specific element to be changed.

path_end

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

Title of the change (optional). 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...
____

The replacement text may additionally include clauses, and not just block content. This is addressed by providing subclauses to the change clause [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.3.0].

For each such subclause, auto-numbering macros need to be provided independently.

No change metadata is provided for the subclauses: the change metadata for the change clause applies to the replacement text as a whole.

[change=add,locality="clause=3.1.2.16"]
== 3.1.2

Add the following terminological entries after 3.1.2.13:

=== 3.1.2.14 pass-format:metanorma[<br/>]canonical form

autonumber:example[1]
autonumber:table[3]

date and time expression where all its time scale components are _normalised_
(3.1.2.15)

====
Example 1 in the document
====

NOTE: Note 1 to entry: A

|===
|A |B
|===

Note

There is no current support for specially formatted subclauses, such as terms. In the foregoing example, the formatting of terms in ISO is done by putting a linebreak between term number and preferred term, and by providing the term note label "Note 1 to entry" as explicit text in the note, which is otherwise unnumbered and thus unlabelled.

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.