A draft of errors rendered inline with links

[ndw]

Per my action on the 5 April 2022 CG meeting, this draft is an /alternate/ solution to the question of how to identify errors with specific error codes in the specification. In this version, rather than interrupting the flow of the prose with specific error conditions, the errors are pointed to via links.

This is an /alternative/ to #54

A readable view of this version is available here: https://ndw.github.io/ixml/errcodes2.html

[ndw]

This draft also fixes #61.

[cmsmcq]

This helps keep the prose light-weight and airy. But I am uneasy about the rendering as superscript error codes. My best attempt to understand why produces these reasons:

• It looks a bit like a footnote reference, but the error codes don't look like footnote numbers.
• Taken as an annotation, I interpret the hyperlinked error code as short-hand for "A violation of this constraint raises the error whose coded identifier is S005", or similar, and for reasons I do not think I understand the lack of whitespace between the word preceding the annotation and the superscript number makes me think it relates to that word rather than to the sentence as a whole. (That should not be the case, given how footnotes work. But I report the phenomenon as it presents itself to my experience.)
• Unless we increase the default leading of the text, superscripts like this cause (at least in the browsers I usually use) uneven line spacing, which this reader finds visually distracting.

Looking at examples, I find myself reminded of the embedding of well-formedness and validity constraints in the grammar of XML, and thinking it might work better with a similar notation. Instead of a superscript error code, perhaps just a bracketed annotation. So instead of

The mark must be a valid mark character^S006.

perhaps something like

The mark must be a valid mark character [error code: S006].

Some people might prefer "EC:" over "error code:" as being briefer; either way we'll need an explanation somewhere.

The analogy with WFCs and VCs in the XML spec makes me think it might work to put the full text of the error description in a block after the current paragraph.

[ndw]

Steven felt that a more direct presentation of the errors, along the lines you suggest, though not precisely as you suggest, interrupted the narrative flow of the prose. See https://ndw.github.io/ixml/errcodes.html

I will see if I can find a compromise between the two positions and post a third draft for consideration.

[cmsmcq]

Understood. I believe that using an inline annotation like "[EC: S006]" does not interrupt the flow materially more than a superscript "S0006". (Because it does not suggest a footnote reference and does not disrupt HTML formatting, I think it interrupts the flow less, despite using more ink.)

As for my second suggestion, well, I believe that displaying the error code and message as a block (perhaps a block with distinctive formatting) can make it less intrusive into the text flow than inlining it. (It seems counter-intuitive, but I think it makes it easier to skip the block and proceed to where the normal prose continues.) Others may disagree, of course.

[ndw]

The CG decided to go with "option 3". This PR is abandoned.