Validation

All Metanorma XML documents that are generated by the Metanorma tool are validated against a formal schema for the document structure, as well as style rules around content.

Validation messages are written to:

console (standard error, STDERR);
an error log file (the filename of the current document, suffixed with .err.html), with messages sorted by error class and location in the text [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.21], as well as priority, and (where possible) with a hyperlink to the corresponding location in the generated HTML output [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.2].

The error log file has the following structure:

Error class

Line number (where available)

ID of element (where available)

Message

Context (by default, Metanorma XML)

Severity

There are four severity values, 0 through 3. Severity 0 causes execution to abort, and alerts about such fatal errors are also output to console. To date, these are applicable to all flavours of Metanorma, and are documented here. Severity 3 errors, by contrast, are information-only warnings. You must address severity 0 errors, to get documents to compile at all, and you should also address severity 1 errors.

Error classes include the following:

Style issues

Style: These are typically specific to the SDO, and reflect requirements on content set by the SDO editorial group. For example, ISO Content style validation lists the ISO-specific content style rules that Metanorma warns about when compiling ISO documents, derived from ISO/IEC DIR 2 and from the ISO House Style specification. These issues will not prevent compilation, and they are not always correct, but they do catch the kinds of issues that SDO editorial review is supposed to identify.

Markup issues

Anchors: Issue with identifiers of document elements, or resources (including URIs)
AsciiDoc Input: Issue with AsciiDoc markup, likely to prevent parsing of document
Bibliography: Issue with bibliographic markup
Crossreferences: Issue with cross-reference to document elements
Document Attributes: Issue with content of AsciiDoc document attributes
Images: Issue with images
Include: Issue with includes
Maths: Issue with mathematical expressions
Requirements: Issue with Metanorma requirements markup
Table: Issue with table format
Terms: Issue with terms & definitions format

Deciphering what has gone wrong with them may take more effort, but the errors they point to are more serious than the style errors, and typically need to be resolved for the document to be well-formed.

The following are fatal errors (Severity 0) identified as markup issues:

Anchors

Malformed URL
Duplicate, ambiguous anchor in file

Bibliography

Reference to an IEV term (International Electrochemical Vocabulary) that does not exist; see Sourcing concepts from termbases.
Missing local Relaton data source file; see Importing bibliographic records from other formats.

Crossreferences

Issue with cross-reference to document elements

Invalid specification of index term (too many attributes, suggests missing quotation marks around a term containing a comma)
Mismatch of callouts and annotations on sourcecode snippet

Images

Issue with images

Image file not found

Include

Issue with includes

Specified include file does not exist.

Note

This issue also arises if the include is block-commented: Asciidoctor does not take block comments into account when it processes includes. Metanorma is more strict in enforcing the existence of included files than Asciidoctor is natively. To prevent bad includes from aborting execution, either put a :novalid: document attribute in the document, to prevent checking for fatal errors, or else comment out the include with a line comment instead of a block comment:

//include:missing-file[]

instead of

////
include:missing-file[]
////

Maths

Issue with mathematical expressions

Malformed MathML expression (whether entered as MathML, or after being converted from any math sytnax)

Requirements

Issue with Metanorma requirements markup

(In Modspec) requirement identifier is used more than once

Table

Issue with table format

Inconsistent number of rows specified (rowspan)
Inconsistent number of columns specified (colspan)

Terms

Issue with terms & definitions format

Concept markup ({{…}}) points to something which is not a term or symbol

Style issues

Style: These are typically specific to the SDO, and reflect requirements on content set by the SDO editorial group. For example, ISO Content style validation lists the ISO-specific content style rules that Metanorma warns about when compiling ISO documents, derived from ISO/IEC DIR 2 and from the ISO House Style specification.

Conformance to Metanorma XML

Metanorma XML Syntax: Issue with validation of Metanorma Semantic XML. These errors deal with such things as restrictions on what kinds of text can appear where, pointers within the document that are orphaned, and elements that appear in the wrong sequence. The gem will usually (but not always!) generate HTML and Word output despite the presence of those errors. These errors can proliferate as the schema is quite strict, and should be investigated only when the document is visibly wrong; they are demoted to severity 2.