Metanorma: Aequitate Verum

Author's documentation

Validation of Metanorma XML output

General

Metanorma documents are compiled into the authoritative Metanorma Semantic XML format, which is validated against an XML schema for document structure, style rules around content.

Validation message output channels

Validation messages are output to the following channels:

  • console (standard error, STDERR);

  • an error log file (the filename of the current document, suffixed with .err.html).

In the error log file, messages are shown by:

Validation log structure and severity levels

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.

  • Alerts about fatal errors are also output to the console.

  • Must be addressed to get documents to compile.

Severity 1

  • Should be addressed to ensure document correctness.

Severity 2

  • Less critical but should be investigated if the document is visibly wrong.

Severity 3

  • Information-only warnings.

These severity values are applicable to all flavours of Metanorma.

Filtering

The error file can get quite large, and it is possible to filter certain classes of log messages from the error log:

Example 1. Filtering out all messages of severity 3 and all messages from the categories
:log-filter-severity: 3
:log-filter-category: Crossreferences,Document Attributes,Metanorma XML Syntax

Validation error classes

General

Each error class is a category of error that Metanorma can detect. The error classes are not exhaustive, and new error classes may be added as new functionality is added to Metanorma.

Style validation error classes

Style

These are typically specific to the SDO, and reflect requirements on content set by the SDO editorial group. 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.

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.

Markup validation error classes

Markup issues are typically more serious than style issues, and may prevent the document from being well-formed.

Markup issues usually need to be resolved for the document to be properly compiled.

Note
 Deciphering what has gone wrong with markup issues may take more effort than style issues.
Anchors

Issue with identifiers of document elements, or resources (including URIs)

Severity 0 (fatal)

  • Malformed URL

  • Duplicate, ambiguous anchor in file

AsciiDoc Input

Issue with AsciiDoc markup, likely to prevent parsing of document

Bibliography

Issue with bibliographic markup

Severity 0 (fatal)
Cross-references

Issue with cross-reference to document elements

Severity 0 (fatal)

  • 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

Document Attributes

Issue with content of AsciiDoc document attributes

Images

Issue with images

Severity 0 (fatal)

  • Image file not found

Include

Issue with includes

Severity 0 (fatal)

  • The specified file indicated in the include command does not exist.

    Note

    It is important to note that "block comments" (comments delimited by ////) do not comment out the include command. If an include command is given in a block comment, the include command will still be processed and the contents included in the commented out text. This means that if the included file does not exist, the "missing include file" error will be raised, as Metanorma is more strict in enforcing the existence of included files than a typical AsciiDoc processor.

    To prevent bad includes from aborting execution, either:

    • skip checking for fatal errors entirely by putting a :novalid: document attribute in the document; or

    • comment out the include command with a "line comment" (a line starting with //) instead of a "block comment", as follows:

       // include:missing-file[]

      instead of

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

  • Specified boilerplate file does not exist (:boilerplate-authority:) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.7].

Maths

Issue with mathematical expressions

Severity 0 (fatal)

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

Requirements

Issue with Metanorma requirements markup

Severity 0 (fatal)

  • (In Modspec) requirement identifier is used more than once

Table

Issue with syntax of table declarations.

Severity 0 (fatal)

  • Inconsistent number of rows specified (rowspan)

  • Inconsistent number of columns specified (colspan)

Terms

Issue with syntax in the terms and definitions clauses.

Severity 0 (fatal)

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

  • Designation markup (preferred:[], admitted:[], deprecated:[]) used in a clause not recognised as a terms clause

Metanorma XML Syntax

Issue with validation of Metanorma Semantic XML.

Severity 0 (fatal)
Severity 2 (info)

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.

Metanorma will usually 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.