Page MenuHomePhabricator

Decide whether to support "extends" in the references section
Closed, ResolvedPublic3 Estimated Story Points

Description

Discussion split from T151305#5723309 and following.

Should we allow subreferences to be declared inside the references section?
This is difficult on a technical level, because this case cannot be detected early enough to do footnote numbering correctly. See parser test "Extends <ref> defined in <references> called with #tag", and this example:

<ref name="child" />

<references>
<ref name="parent">All about a book.</ref>
<ref name="child" extends="parent">page 10</ref>
</references>

If this will be allowed, we need to figure out how to support it and possibly require a weird syntax like <ref name="child" extends="parent />. If not, then we should display an error.

Event Timeline

WMDE-Fisch set the point value for this task to 3.Dec 11 2019, 12:17 PM

For now, lets add an error message when this case occurs. We can decide on a different solution later. Story points are for adding the error message.

I think silent failure, or using something other than class=error, might be preferable here if it's the case, and I already suggested it will be, the community will want support for such. I'd rather field questions of "why doesn't it work?" than "there's a big red error for something that should work". One might reasonably make a category for it though, without the red error.

If this will be allowed, we need to figure out how to support it and possibly require a weird syntax like <ref name="child" extends="parent" />.

That workaround might be reasonable.

Can you further elide what makes this case difficult versus the general LDR case or the general arbitrary location of <ref name> with definition case (it used to be a requirement that the defined named ref needed to be first in the document)?

Change 556401 had a related patch set uploaded (by Thiemo Kreuz (WMDE); owner: Thiemo Kreuz (WMDE)):
[mediawiki/extensions/Cite@master] Add parser tests for reused extended <ref> before defined

https://gerrit.wikimedia.org/r/556401

The difference is that for the "general LDR case" the parser is able to decide on an index number the moment the first <ref name="…" /> appears somewhere in the text. It doesn't matter if the full reference appears before or after this point. The numbers are simply incremented from the top of the document to the bottom.

This is different when the <ref name="…" /> is pointing to a later reference that turns out to be an extended one. There is no way to know this the moment the <ref name="…" /> appears in the text.

It might be possibly to solve this by utilizing the Parsers marker feature (see Parser::insertStripItem), or by heavily increasing the complexity of Cites internal call stack.

Change 556401 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Add parser tests for reused extended <ref> before defined

https://gerrit.wikimedia.org/r/556401

Just a note during sprint planning: I think we can omit this feature from the MVP, by agreeing to always error if a ref is written using "extends" in some reuses but not others.

For now we decided on supporting this feature by using the technique described in T242141: Bad numbering when reusing a sub-reference before it's defined. We might come back to this but would create a new ticket for a different approach.