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,
an error file (the filename of the current document, suffixed with
.err), with messages sorted by error class and location in the text, [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.21].
During build you may see a sequence of warnings — please pay attention to them!
Content style rules
The content style warnings come first, and are prefixed with
<flavor name> Style.
Currently, among officially supported Metanorma document flavors, content style rules are only implemented for ISO standards. There is no generic reference for content style rules; if you’re using the Metanorma to author ISO documents, see Metanorma ISO flavor docs for ISO-specific content style rules.
The syntax errors come afterwards, and are of two classes: warnings and errors generated in the code, and errors generated by parsing the generated Metanorma XML against the document schema. Parsing errors report the line number and line position of the syntax error; code generated errors cannot report a line number, and instead supply the nearest internal cross-reference where possible. 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.
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 need to be resolved for the document to be well-formed. The gem will usually (but not always!) generate HTML and Word output despite the presence of those errors.
value of attribute "date" is invalid; must be an ISO date @ 454:183 element "review" missing required attribute "from" @ 454:183 element "subsection" not allowed here; expected the element end-tag or element "admonition", "dl", "example", "figure", "formula", "note", "ol", "p", "quote", "review", "sourcecode", "table" or "ul" @ 467:52 value of attribute "date" is invalid; must be an ISO date @ 476:233 IDREF "Annex-A-2" without matching ID @ 315:50 IDREF "last_conformance_class" without matching ID @ 649:236 IDREF "Annex-A" without matching ID @ 308:141
The Metanorma XML schema seeks to be consistent as much as possible across flavours, but individual flavours have rules of their own, which are policed through syntax validation.
The tool also validates terms cited from the International Electrotechnical Vocabulary (IEV) against the online IEV Electropedia entries. If the preferred term does not match the form given in the IEV for that entry, it will issue a warning.