To handle a variety of Cite errors, we propose the following:
- All citations will use <sup> tags and those in error include mw:Error metadata annotation in the typeof attribute and a data-mw='{"errors":[{"key":"cite_error_ref_no_input"}]}. This example includes the i18n error key of cite_error_ref_no_input which the client would look up for the actual english or other language error message.
- We are recommending that all error messages show up in the references section, not in the actual article text. This is in contrast to core where if the error happens while processing refs, it's inlined. If the error happens when building the references list, the error is inserted there. That's seems to be a by-product of the implementation, and is not necessarily achieving the goal of the best user experience.
There are benefits to having the errors inline, like where the problem occurs is obvious and more likely to be fixed, and broken citations don't give a sentence more weight in the reader's eyes, but we feel these can just as easily be accomplished by CSS styling based on the mw:Error annotation.
Continuing to output <sup> tags even for erroneous refs means that current clients will likely not need any changes other than doing what they want with the mw:Error and so no major version bump for Parsoid's HTML would be necessary.
Also I don't expect to need to use "mw:Placeholder" as VE and other clients should be able to just ignore a citation without actual content and Selser will round trip the error correctly, and not cause the error text to become the content, while still allowing an editor to edit the content at a point of citation which will then replace the error message.
Implementation details:
This will require for some error types, saving additional data to allow mw:Error to be inserted at the point of citation if the error could not be determined during the first pass. We can collect pointers to potential errors on the first pass and release them when they're proven not to be errors. At the end there is a concise collection to annotate.
An example where this can happen are named refs with no content and no other identically named ref found on a page with content.
An example of correct citation inline and references html output for comparison to proposed incorrect citation missing content/text in result output below
zero<ref name="one">two</ref>
<references />
<p>zero<sup about="#mwt3" class="mw-ref" id="cite_ref-one_1-0" rel="dc:references" typeof="mw:Extension/ref" data-mw='{"name":"ref","attrs":{"name":"one"},"body":{"id":"mw-reference-text-cite_note-one-1"}}'><a href="./index.php%3Ftitle=CiteTest#cite_note-one-1" style="counter-reset: mw-Ref 1;"><span class="mw-reflink-text">[1]</span></a></sup></p>
<div class="mw-references-wrap" typeof="mw:Extension/references" about="#mwt6" data-mw='{"name":"references","attrs":{}}'><ol class="mw-references references" data-parsoid="{}"><li about="#cite_note-one-1" id="cite_note-one-1" data-parsoid="{}"><a href="./index.php%3Ftitle=CiteTest#cite_ref-one_1-0" rel="mw:referencedBy"><span class="mw-linkback-text">↑ </span></a> <span id="mw-reference-text-cite_note-one-1" class="mw-reference-text">two</span></li></ol></div>Incorrect citation inline (no content/text) produces an editable citation inline, but no inline error message, which is located in the references text. In this case the i18n error message key cite_error_references_no_text is included in the data-mw errors property.
zero<ref name="one"></ref>
<references />
<p>zero<sup about="#mwt3" class="mw-ref" id="cite_ref-1" rel="dc:references" typeof="mw:Extension/ref mw:Error" data-mw='{"errors":[{"key":"cite_error_ref_no_text"}],"name":"ref","attrs":{},"body":{"id":"mw-reference-text-cite_note-1"}}'><a href="./Main_Page#cite_note-1" style="counter-reset: mw-Ref 1;" data-parsoid="{}"><span class="mw-reflink-text" data-parsoid="{}">[1]</span></a></sup></p>
<div class="mw-references-wrap" typeof="mw:Extension/references" about="#mwt6" data-mw='{"name":"references","attrs":{}}'><ol class="mw-references references" data-parsoid="{}"><li about="#cite_note-1" id="cite_note-1"><a href="./Main_Page#cite_ref-1" rel="mw:referencedBy"><span class="mw-linkback-text">↑ </span></a> <span id="mw-reference-text-cite_note-1" class="mw-reference-text"></span></li></ol></div>