Categorise messages sent to the console output

[ghobona]

The message log should tag messages according to different categories, for example:

• Informative notices (e.g. [relaton-iso] ("ISO 19101-1:2014") Found exact match.)
• Warnings for Developers (e.g. Calling 'DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated. Please call 'DidYouMean.correct_error(error_name, spell_checker)' instead.)
• Warnings for Editors (e.g. Metanorma XML Style Warning: (XML Line 000265): Hanging paragraph in clause)
• Fatal Errors (i.e. those that cause compilation to abruptly end)

[opoudjis]

Warnings for Developers

That particular one, I likely won't be able to intercept, it is straight out of Ruby proper.

All messages are categorised in the log that is generated, and I am wary of outputting too much to the screen; if anything, the syntax validation errors should probably go to log-only. But one-word categorisation is doable, although a big project, given the number of gems and that at least three developers are involved.

[opoudjis]

hyperlinked HTML rendering of log

[ghobona]

@opoudjis @ronaldtse Here is an example of a zip file containing example compliance test results.

The file ./result/index.html is created by parsing the xml file testlist.xml.

The HTML file, when rendered, presents a human friendly display of the results, whereas the XML file is aimed at applications.

A similar approach could be taken for the metanorma err file.

[opoudjis]

Log errors can be reported, depending on where they are caught in processing, as:

• Asciidoctor line, for errors caught before Asciidoctor is converted to XML
• Asciidoctor section, for errors caught before Asciidoctor is converted to XML, where we cannot recover the line number
• XML line, for schema errors
• node ID, for errors caught after Asciidoctor is converted to XML

What we want for hyperlinked errors is node IDs: they convert readily to anchors.

We need to be able to convert XML line numbers to the preceding node ID.

We need to convert Asciidoctor Section titles to their corresponding node ID.

If at all possible, we also need to convert Asciidoctor line numbers to node IDs.

If we cannot generate HTML, we also need to have recourse to a log file incorporating Asciidoctor snippets.

[opoudjis]

There are 213 instances of errors being logged in Metanorma. (All of them are in the generation of Semantic XML, the downstream processing of Presentation XML does not generate much in the way of errors.)

94 of those errors are not associated with a location. Many of them could be, but it wasn't a priority with text files.

One error is the XML schema validation, referencing the XML line.

4 operate on raw Asciidoctor.

The rest are generated from XML, and invoke node ids.

So only five log entries need to be modified to generate linkable anchors.

[opoudjis]

XML schema validation: adding to log message the XML line where the error is, and the nearest node id for hyperlinking in the HTML. (Nil, if the error occurs before any node anchors, e.g. in bibdata.)

[opoudjis]

New problem: now that we are using IDs to link to errors, if we then process the text to get rid of the anchor, the link breaks. This happens in missing terms.

[opoudjis]

Ah, what's actually happening is that the content hash-based IDs for anchors are overwriting the IDs against which errors were reported. We need to pass the before and after anchors for all such cases to the log module, for mapping.

[opoudjis]

Edge case: huge long IDs need to be broken up, as we already do in tables in isodoc. Moving the relevant code from isodoc to metanorma-utils.

[opoudjis]

I'm satisfied with where this has got to. @ghobona you might want to discuss the formatting in a new ticket, but I'm attaching a pair of the new, HTML-based error output and the HTML file it hyperlinks to.

Archive.zip