Page MenuHomePhabricator

Collect use cases for interactions with refined <ref>s
Closed, ResolvedPublic3 Estimate Story Points

Description

Collect rules (test cases) for interactions between attributes, e.g.:

  • Cannot refine a subreference
  • Cannot have refines and reuse an existing reference ("name" attribute and empty child content) → Is this true? Might work just fine.

This task is about collecting the use cases, ideally as actual test code (parser tests, better separate unit tests if possible).

Original estimation: 3

Details

Related Gerrit Patches:

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptOct 23 2019, 1:00 PM
thiemowmde set the point value for this task to 3.Oct 24 2019, 7:17 AM

Just as a first collection...

Disclaimer: The examples below always represent the full wiki text in the example.

Allowed:

<ref name="foo">book</ref>
<ref refines="foo">page 1</ref> //refines the book with "page 1"
<ref name="foo">book</ref>
<ref refines="foo" name="bar">page 1</ref> //refines "book" with "page 1"
<ref name="bar" /> // a 2nd usage of the refinement of "book" with "page 1"

Also assume a random order for the above examples.

<ref refines="foo">page 1</ref> //refines the book with "page 1"
<references>
  <ref name="foo">book</ref>
</references>

Questionable:

<ref name="foo">book</ref>
<ref refines="foo" /> // no text for the refinement
<ref name="foo">book</ref>
<ref refines="foo"></ref> // empty text for the refinement
<ref name="foo">book</ref>
<ref refines="foo"> </ref> // de-facto empty text for the refinement

Not allowed/errors:

<ref refines="foo">page 1</ref> //foo is not defined
<ref>book</ref>
<ref refines="foo">page 1</ref> //foo is not defined
<ref name="foo" /> //foo is empty
<ref refines="foo">page 1</ref>

The above example will also show an error in the "default" behavior, when a named reference is not defined.

<ref name="foo">book</ref>
<ref name="foo">magazine</ref> // foo is defined twice
<ref refines="foo">page 1</ref>

The above example will also show an error in the "default" behavior, when a named reference is defined twice.

thiemowmde added a comment.EditedOct 24 2019, 2:20 PM

I believe all 3 "questionable" examples should fail. A refinement isn't refining anything if it does not have any content.

Overall, from experience I know it's much better do disallow as much as possible, and only allow as few use cases as possible. It's much easier to allow specific use cases later, than to disallow some that might already be in uses somewhere. This way around we will automagically come up with a controlled set of use cases.

More:

Refining the same base multiple times is fine (pretty much the whole purpose of this feature)
<ref name="a">book</ref>
<ref refines="a">page 2</ref>
<ref refines="a">page 3</ref>
Naming refinements is fine
<ref name="a">book</ref>
<ref refines="a" name="b">page 2</ref>
<ref refines="a" name="c">page 3</ref>
<ref name="b" />
<ref name="c" />
Cant reuse a name for 2 refinements
<ref name="a">book</ref>
<ref refines="a" name="b">page 2</ref>
<ref refines="a" name="b">page 3</ref>
Cant refine a refined ref (no nesting)
<ref name="a">book</ref>
<ref refines="a" name="b">page 2</ref>
<ref refines="b">section 3</ref>

Still missing here: interactions with the group="…" and follow="…" attributes.

follow="…" is described here: https://www.mediawiki.org/wiki/Extension:Cite#Merging_two_texts_into_a_single_reference. I suggest this:

Refining a multi-part ref should be fine
<ref name="a">part 1</ref>
<ref follow="a">part 2</ref>
<ref refines="a">ok</ref>
Dont allow splitting a refinement for now (even if theoretically possible)
<ref name="a">book</ref>
<ref refines="a" name="b">page 2</ref>
<ref follow="b">and page 3 the same time?</ref>
Cant be a follow up and a refinement the same time
<ref name="a">book 1</ref>
<ref follow="a" refines="a">huh?</ref>
Not even when referencing 2 different bases
<ref name="a">book 1</ref>
<ref name="b">book 2</ref>
<ref follow="a" refines="b">huh?</ref>
awight added a comment.EditedOct 29 2019, 9:38 AM
Naming refinements is fine
<ref name="a">book</ref>
<ref refines="a" name="b">page 2</ref>
<ref refines="a" name="c">page 3</ref>

It's worth mentioning that the named subreferences can be used as normal:

<ref name="b" />
thiemowmde added a comment.EditedOct 30 2019, 9:21 AM

Yes, thanks! I updated my examples above.

Interactions with group="…":

Everything in the same group
<ref group="g1" name="a">book</ref>
<ref group="g1" refines="a" name="b">page</ref>
<ref group="g1" name="b" />
Base and refinement in different groups
<ref group="g1" name="a">book</ref>
<ref group="g2" refines="a">page</ref>
Refinement in the unnamed default group
<ref group="g1" name="a">book</ref>
<ref refines="a">page</ref>
Base in the unnamed default group
<ref name="a">book</ref>
<ref group="g1" refines="a">page</ref>

Change 547746 had a related patch set uploaded (by Andrew-WMDE; owner: Andrew-WMDE):
[mediawiki/extensions/Cite@master] [WIP] Begin adding parser tests for refined references

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

Change 548758 had a related patch set uploaded (by Thiemo Kreuz (WMDE); owner: Thiemo Kreuz (WMDE)):
[mediawiki/extensions/Cite@master] Block all combinations of refines="…" and follows="…"

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

awight closed this task as Resolved.Nov 6 2019, 12:41 PM
awight claimed this task.
awight moved this task from Demo to Done on the WMDE-QWERTY-Sprint-2019-10-23 board.

Change 549811 had a related patch set uploaded (by Awight; owner: Awight):
[mediawiki/extensions/Cite@master] Split out BookReferencing parser tests

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

awight reopened this task as Open.Nov 8 2019, 9:13 AM
awight reassigned this task from awight to Andrew-WMDE.
awight moved this task from Sprint Backlog to Review on the WMDE-QWERTY-Sprint-2019-11-06 board.

Change 547746 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Add parser tests for refined references as rendered right now

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

Change 549811 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Split out BookReferencing parser tests

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

Change 548758 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Block all combinations of refines="…" and follows="…"

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

thiemowmde closed this task as Resolved.Nov 20 2019, 12:56 PM