As part of the Book-Referencing project we introduced and rephrased several Cite error messages. This ticket is to collect these message (in their intermediate wording) and review and possibly rephrase them together with WMDE-Design (UX) at the end of the project.
We ended reusing existing messages a lot:
- cite_error_ref_no_input: Invalid <ref> tag; refs with no name must have content. This simply happens when a <ref extends="…"></ref> is technically valid, but does not have content (or no visible content, e.g. only spaces). Can be rephrased (e.g. let it say "no visible content"), but should still be ok for all types of refs, not only extended ones.
- cite_error_ref_no_key: The opening <ref> tag is malformed or has a bad name. Happens when there is only <ref extends="…" />. This is entirely broken, and we can only guess what the intention might have been. Might just be incomplete (with the content and the closing </ref> missing), or a broken reuse (with the name missing).
- cite_error_ref_too_many_keys: Invalid <ref> tag; invalid names, e.g. too many. Happens when combining the follow feature with an incompatible one, e.g. extends or a name. This is so rare, we did not wanted to introduce a new message before we are sure it makes sense. Suggestions: "Invalid <ref> tag, follow cannot be used in combination with name or extends", "Invalid <ref> tag, follow cannot be combined with other features".
- cite_error_references_duplicate_key: Invalid <ref> tag; name "$1" defined multiple times with different content. This appears a lot not only when the content of two ref conflicts, but also when the definition of two sub-refs conflicts. E.g. two sub-ref that both say "page 2", and both use the same name, but refer to two different parents. The full definition of the two ref in this example is then "Parent A page 2" and "Parent B page 2". In other words: In some sense, the content of the two sub-refs is identical. It's "page 2" in both cases. But the full content of the two ref, including the parent, conflicts. Other possible wordings: "<ref name="$1"> defined multiple times with different content or different meaning", "Two conflicting <ref name="$1"> exist, e.g. with different content or different parent".
- cite_error_references_no_text: Invalid <ref> tag; no text was provided for refs named $1. Happens in two situations. When a sub-ref points to a parent that is missing or can not be found by name (e.g. because of a typo in the name). The code will assume the parent exists, actually creating a dummy parent, but will complain in the end when there was never a ref that put content into that dummy parent. The other situation is if the user tries to reuse a sub-ref by name only. This is not valid. Reusing a sub-ref must be done with the name and repeating the extends attribute. If the extends is missing, the code will assume the name points to a top-level ref instead of a sub-ref. As before, in the end the code will complain about this dummy top-level ref never getting any content.
These are our new messages:
- cite_error_ref_nested_extends: Extending <ref> tags more than one level deep is not allowed. This is an intentional, but ultimately arbitrary limitation we had to put in place to keep the complexity low. Other possible wordings: "a sub-ref can not have a parent that is also a sub-ref", "sub-refs cannot be nested", "extended refs cannot be nested".
- cite_error_included_references: Closing tag missing for <references>. We had to introduce this technical limitation because users actually run into this, and it gave us headaches. See T242437. Technically, the wording could as well be "nesting <references> tags is not allowed".
- cite_error_ref_no_parent: Invalid <ref> tag depends on an unknown ref named "$1". Introduced for T240858.
For reference, here are all other messages:
- cite_error_empty_references_define: <ref> tag defined in <references> with name "$1" has no content.
- cite_error_group_refs_without_references: <ref> tags exist for a group named "$1", but no corresponding <references group="$1"/> tag was found
- cite_error_included_ref: Closing </ref> missing for <ref> tag
- cite_error_no_link_label_group: Ran out of custom link labels for group "$1". Define more in the <nowiki>[[MediaWiki:$2]]</nowiki> message.
- cite_error_ref_invalid_dir: Invalid dir="$1", must be ltr or rtl
- cite_error_ref_numeric_key: Invalid <ref> tag; name cannot be a simple integer. Use a descriptive title
- cite_error_references_group_mismatch: <ref> tag in <references> has conflicting group attribute "$1".
- cite_error_references_invalid_parameters: Invalid parameter in <references> tag
- cite_error_references_missing_group: <ref> tag defined in <references> has group attribute "$1" which does not appear in prior text.
- cite_error_references_missing_key: <ref> tag with name "$1" defined in <references> is not used in prior text.
- cite_error_references_no_backlink_label: Ran out of custom backlink labels. Define more in the <nowiki>[[MediaWiki:Cite references link many format backlink labels]]</nowiki> message.
- cite_error_references_no_key: <ref> tag defined in <references> has no name attribute.