Persistent error logs for more effective document engineering
Metanorma now provides persistent error logs for detailed debugging post-compilation. This post explains how to navigate and utilize these logs effectively.
Introduction
Metanorma users often encounter numerous error messages in the console log during document compilation. These messages are sometimes overwhelming, but are important for maintaining document quality.
Recently, Metanorma has improved its error logging by saving these logs to disk, including grammar errors, allowing them to persist for detailed debugging post-compilation.
This post explains how to navigate and utilize these error logs effectively.
Further details on how to use error logs can be found in the Validation documentation.
Error severity levels
Metanorma categorizes errors into four severity levels:
- Severity 0
- Fatal errors that prevent document compilation.
- Severity 1
- Critical errors that should be addressed.
- Severity 2
- Warnings that can often be ignored.
- Severity 3
- Informational messages.
Error categories
Errors are grouped into categories to streamline the troubleshooting process.
The main categories include the following.
Style- Potential violations of the standard-defining organization's (SDO) house style.
Metanorma XML Syntax- Strict XML syntax checks, usually Severity 2.
Relaton- Issues with references from the Relaton bibliographic database.
Metanorma Markup- Various issues such as:
Anchors- Issues related to the use of anchors within the document, such as duplicate or missing anchors.
AsciiDocInput- Errors originating from the AsciiDoc source input, including syntax errors and invalid constructs.
BibliographySyntax- Problems with the bibliography section, such as incorrect citation formats or missing references.
Cross-references- Errors in cross-referencing within the document, including broken links or incorrect reference targets.
Document Attributes- Issues with document attributes, such as missing or incorrectly defined attributes.
Images- Problems related to image inclusion, such as missing image files or incorrect image paths.
Include- Errors with included files, such as missing files or incorrect paths.
Maths- Issues with mathematical expressions, including syntax errors in math markup.
Requirements- Problems related to requirements sections, such as missing or incorrectly formatted requirements.
Table- Errors in table formatting, including incorrect table syntax or missing table elements.
Terms- Issues with the terms section, such as missing definitions or incorrect term formatting.
Filtering errors
General
Metanorma provides two mechanisms to filter errors in the logs, making it easier to focus on the most critical issues.
Filtering by severity
The first mechanism is filtering by severity. By setting the :log-filter-severity: attribute, users can exclude errors below a certain severity level. This allows users to concentrate on more severe issues that require immediate attention.
The following configuration as a document attribute will omit Severity 2 and 3 errors from the log.
:log-filter-severity: 2Filtering by category
The second mechanism is filtering by error category. This is done using the :log-filter-category: attribute, where users can specify a comma-separated list of categories to exclude from the log.
Excluding errors from specified categories helps users to streamline the troubleshooting process by focusing on relevant error types.
The following configuration as a document attribute will omit errors from the "Cross-references", "Document Attributes", and "Metanorma XML Syntax" categories.
:log-filter-category: Cross-references,Document Attributes,Metanorma XML SyntaxError log format
The error log for a document {document-name}.adoc is saved as {document-name}.err.html and can be viewed in any browser.
The log starts with a summary of error classes and their counts by severity.
Style: Severity 2: 9 errors
Metanorma XML Syntax: Severity 2: 7 errors
Each error class links to detailed listings, allowing quick navigation.
Errors are styled by severity for easy identification:
- Severity 0
- Boldface on a pink background
- Severity 1
- Boldface
- Severity 2
- Normal type
- Severity 3
- Italicized and grey
Error details
Each error is presented in a table with the following columns:
- Line
- The line number in the source AsciiDoc where the issue occurred.
- ID
- The identifier of the location, which could be a clause number, GUID, anchor, or line number in the Metanorma XML file. Hyperlinks are provided for anchors.
- Message
- A description of the error.
- Context
- Two lines of surrounding Metanorma XML to help locate the error.
The output looks like this.
Line ID Message Context Severity 000064 _a172c0b4-4751-941d-b6c5-344768eb7b1b Formula +_a172c0b4-4751-941d-b6c5-344768eb7b1b+ has not been cross-referenced within document a .... <formula id="_a172c0b4-4751-941d-b6c5-344768eb7b1b"> <asciimath>dot Theta ne ddot Theta</asciimath> </formula> .... 2
Conclusion
The Metanorma error logs now provide detailed and comprehensive information about each issue, including the severity level, error category, and specific line numbers in the source document. This allows users to pinpoint the exact location of errors and understand their context.
By leveraging these logs, users can efficiently identify and resolve issues, ensuring high-quality content that adhering to the required standards and guidelines.