Implement "extends"-attribute for ref-tag
Open, NormalPublic

Tokens
"Like" token, awarded by petr.matas."Y So Serious" token, awarded by Addshore."Cookie" token, awarded by jeblad."Love" token, awarded by neilpquinn.
Assigned To
None
Authored By
Tobi_WMDE_SW, Nov 22 2016

Description

Motivation:
Currently, when referencing different sections of the same book, the whole source always needs to be repeated, and the references section may be cluttered by repeated appearances of the same source, with only slight variations. So this is an attempt to bundle the info.

How it should work
The extends parameter gets a string that corresponds to a previously defined reference. e.g. a reference that was named with name="animal" can then be specified through <ref extends="animal">.

<ref extends="animal"> Page 25 </ref> should then lead to "Page 25" being printed in the references section, below the definition of the "animal" source, and with an indent

Mock:

group and extends:
As long as reference names are only unique per group, we stick to that behavior. That means<ref name="A" group="G"> info </ref> can be extended by <ref extends="A" group="G"> details </ref>, but <ref extends="A"> details </ref> will throw an error, unless <ref name="A"> info2 </ref> exists as well.

name and extends:
Extension refs can also have a name. e.g. If there was <ref extends="animal" name="animalpage25"> Page 25 </ref>, <ref name="animalpage25" /> would also link to the extension reference.

Constraints:
It is not possible to make more than one level of extensions (i.e. 1.1.1 never exists).

Implementation
This change needs to be implemented both for parsoid and the cite extension (see subtasks (which are to come ;) )

Task background
This is a concrete implementation task for the proposal that was discussed in T138601.

Background
The wish to improve the referencing of multiple parts of the same source was part of the German-speaking community's technical wishlist in 2013, 2015 and of the international technical wishlist in 2015. For more info, see T100645.

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptNov 22 2016, 10:38 AM
Addshore added a comment.EditedJan 11 2017, 8:18 PM

So, after a quick discussion at Wikimedia-Developer-Summit (2017) with @Bmueller and @Jdforrester-WMF

We need to change

<ref refines="animal" name="animalpage25"> Page 25 </ref>

to

<ref refines="animal" name="animalpage25" refine-data="Page 25"/>

Or something like that

Izno added a subscriber: Izno.EditedJan 11 2017, 11:20 PM

So, after a quick discussion at Wikimedia-Developer-Summit (2017) with @Bmueller and @Jdforrester-WMF

We need to change

<ref refines="animal" name="animalpage25"> Page 25 </ref>

to

<ref refines="animal" name="animalpage25" refine-data="Page 25"/>

Or something like that

That would be unintuitive and inconsistent on the user side.

("A quick discussion" doesn't help the people who weren't there understand the rationale for a design decision.)

@Izno, right, we should add more informations on the reasons, thanks for the heads up! @Jdforrester-WMF, could you add the rationale? Thx!

<ref refines="animal" name="animalpage25" refine-data="Page 25"/>

Wouldn't this make it quite tricky if you want to use complex wikitext, especially with Quotation-marks (with might be generated by templates)?

Why got the wikitext content turned into a plain-text refine-data="…" attribute? Even if I can see the benefits this has, this takes away so much freedom from this proposal that it becomes barely useful. Examples:

  • The community will want to use weblinks in refinements: <ref refines="book">[http://book.com/page5.html#headline Headline, page 5]</ref>
  • The community will want to use templates in refinements: <ref refines="book">{{book|page=5}}</ref>

The change to refine-data="…" is in fact identical to the original proposal of having a page="…" parameter. This was discussed extensively and rejected because it was way to limited for all the possible use cases that are not about pages in a book, e.g.: <ref refines="New York Times">[http://blog.nyt.com/2017/politics …]</ref>. Let's not go back to this, please.

Why got the wikitext content turned into a plain-text refine-data="…" attribute? Even if I can see the benefits this has, this takes away so much freedom from this proposal that it becomes barely useful. Examples:

  • The community will want to use weblinks in refinements: <ref refines="book">[http://book.com/page5.html#headline Headline, page 5]</ref>
  • The community will want to use templates in refinements: <ref refines="book">{{book|page=5}}</ref>

    The change to refine-data="…" is in fact identical to the original proposal of having a page="…" parameter. This was discussed extensively and rejected because it was way to limited for all the possible use cases that are not about pages in a book, e.g.: <ref refines="New York Times">[http://blog.nyt.com/2017/politics …]</ref>. Let's not go back to this, please.

@Jdforrester-WMF would be great if you could check this again in the light of what @thiemowmde is writing above.

jeblad added a subscriber: jeblad.Jan 21 2017, 2:33 AM

Thumbs up from the Norwegian jury! =)

(I like the form <ref refines="book">{{book|page=5}}</ref>, but it is a good solution anyhow.)

Lea_WMDE renamed this task from Implement "refines" parameter for ref-attribute to Implement "extends"-attribute for ref-tag.May 21 2017, 3:36 PM
Lea_WMDE updated the task description. (Show Details)
Lea_WMDE updated the task description. (Show Details)
Anomie added a subscriber: Anomie.May 23 2017, 5:33 PM

Why was this task created in the first place instead of continuing to use T138601?

The extends-attribute inherits the group parameter from the reference it is extending. I.e. <ref name="A" group="G"> info </ref> can be extended by <ref extends="A"> details </ref> and the details will also be shown in group G.

As I said in T138601#2575691, that's not going to work very well. Consider this:

<ref extends="Foo">What does this refine?</ref>

<references>
<ref name="Foo">This one?</ref>
</references>

<references group="Notes">
<ref name="Foo">Or this one?</ref>
</references>

IMO there's little reason not to require the group parameter along with extends if you're extending a reference in a non-default group.

So, after a quick discussion at Wikimedia-Developer-Summit (2017) with @Bmueller and @Jdforrester-WMF

I agree with all the others who think that a "refine-data" property is a terrible idea. So, after discussion here in Phabricator based on the rationale available (i.e. none), it seems clear that the proposal to use a "refine-data" property has been rejected.

Anyone who objects to that is welcome to reopen discussion in this task by presenting their reasoning, rather than just declaring that it "needs" to be changed.

I'm afraid I have to fully agree with @Anomie. Why was T138601 closed? It already contained a lot of insight that appears to got lost now, including the sentence about "group and extends". What is said there just can't work:

The extends-attribute inherits the group parameter from the reference it is extending. I.e. <ref name="A" group="G"> info </ref> can be extended by <ref extends="A"> details </ref> and the details will also be shown in group G.

The problem is how "the reference it is extending" is identified. A reference is not identified by name, but by group and name. It was always possible to have different references in different groups use the same name. It might be possible to change this with the enhancement we are discussing here, and either throw an error when a user attempts to extend a reference with a non-unique name, or try to guess what the user meant and pick one (see @Anomie's example above). But I think doing so would be confusing, inconsistent, and generally a bad idea.

Hi @Anomie and @thiemowmde,
I closed the other ticket to make it visible which is the one we are actually working on (and since it is still reachable I thought this does not make us lose the discussion either). However, if you feel like it should be opened again, or want to link it more visible in this ticket, feel free to do so - I just thought that most of the input from the ticket has been added here. One of the only differences (well spotted ;) ) is the hierarchical inheritance of the group parameter. The reason for this is that according to @Jdforrester-WMF the fact that you currently CAN define references with the same name in different groups is based on an error, which is expected to be fixed. The check whether references have the same name currently happens too late, i.e. after they are split into groups. Therefore, we would throw an error if something is extended and cannot clearly be identified. And after another discussion at Wikimedia-Hackathon-2017 with @Jdforrester-WMF and @daniel we are not pursuing the refine-data property idea, but the solution explained above.

I closed the other ticket to make it visible which is the one we are actually working on (and since it is still reachable I thought this does not make us lose the discussion either). However, if you feel like it should be opened again, or want to link it more visible in this ticket, feel free to do so - I just thought that most of the input from the ticket has been added here.

My question was why this was created in the first place back in November. But given that that happened, merging the two by closing one of them is a good thing.

The reason for this is that according to @Jdforrester-WMF the fact that you currently CAN define references with the same name in different groups is based on an error, which is expected to be fixed.

I've never heard that claim before, and I don't see a task for it. Has any research been done to determine how many existing pages on the various wikis would be broken by "fixing" that?

Izno added a comment.EditedMay 25 2017, 1:46 PM

The reason for this is that according to @Jdforrester-WMF the fact that you currently CAN define references with the same name in different groups is based on an error, which is expected to be fixed.

I've never heard that claim before, and I don't see a task for it. Has any research been done to determine how many existing pages on the various wikis would be broken by "fixing" that?

I would have said this later today if Anomie didn't get to it. That's an entirely separate task and I would guess there will be a good chunk of discussion devoted to the initial claim that it was an error.

This task should proceed from the status quo given the fact that the tech team is working on extension/refinement this year, not a future state that is already disputed (if not definitely by Anomie, definitely by myself, and I would guess the community at-large).

Who wants to open that task? :)

For the record, I don't care whether ref names are changed to be globally unique instead of unique per group. But if that is going to be done it needs to be done in cooperation with the communities to make sure existing pages are fixed beforehand where necessary, and until it is done it would be strange for "extends" to behave as proposed here.

Lea_WMDE updated the task description. (Show Details)May 31 2017, 7:27 PM

@Izno @Anomie @thiemowmde after giving it a good thought I agree with you that name uniqueness per group (as opposed to per article) should be treated at a seperate topic. See corrected task description :)

petr.matas added a subscriber: petr.matas.
petr.matas updated the task description. (Show Details)Jun 25 2017, 3:15 PM

Among other things, I have inserted the words ", unless <ref name="A"> info2 </ref> exists as well" into the task description. If I got the consensual intention wrong, please correct it.

Izno added a comment.Jun 25 2017, 9:55 PM

BTW, I was reading mediawikiwiki:Extension:Cite randomly one day and I bumped into <ref follow="name">: "A typical wikisource issue is, how to merge into one reference texts split into different pages. This can be done using a <ref name="name"> tag for the first part of the reference, and tagging the following parts into different pages with a tag <ref follow="name">."

Don't know how relevant it is....

[…] I have inserted the words ", unless <ref name="A"> info2 </ref> exists as well" into the task description.

This is correct, thanks.

[…] I bumped into <ref follow="name"> […] Don't know how relevant it is.

Fascinating, I never heard of that. These follows are simply concatenated with hard-coded spaces, see https://phabricator.wikimedia.org/diffusion/ECIT/browse/master/includes/Cite.php;88c6531b871a162a84fbdc910454241f4e3fcf8b$457. This does not solve the problem we want to solve here, because we want each extends to be a separate, non-concatenated reference with a separate name and number, but nested (extends are numbered "1.2" instead of just "1").

Question to @Lea_WMDE: Note that follow="…" does not end with an "s". Should we stick to this and change the proposed extends="…" to extend="…"?

Note that follow="…" does not end with an "s". Should we stick to this and change the proposed extends="…" to extend="…"?

Although it is not me who has been asked, I would prefer extends="…". This makes it clear that this extends that, and not this is extended by that.

But I would prefer parent as the name of the attribute. In my opinion it explains best what is going on.

Izno added a comment.Jul 20 2017, 10:30 PM

This does not solve the problem we want to solve here, because we want each extends to be a separate, non-concatenated reference with a separate name and number, but nested (extends are numbered "1.2" instead of just "1").

Less a "here's a possible already-existing solution" (I didn't believe it was) and more a "do you need to spend time considering compatibility between extends and follow?".

Although it is not me who has been asked, I would prefer extends="…". This makes it clear that this extends that, and not this is extended by that. But I would prefer parent as the name of the attribute. In my opinion it explains best what is going on.

I agree. Not a particular fan of parent.

@Izno @petr.matas @thiemowmde thanks for your inputs! For the names I have opened a new ticket T171581 to have a room to discuss them. My current gut feeling though is, that if we stick to extend(s) we should probably keep the s for a better understanding of direction, as @petr.matas stated.

Izno added a comment.Jul 25 2017, 1:47 PM

@Izno @petr.matas @thiemowmde thanks for your inputs! For the names I have opened a new ticket T171581 to have a room to discuss them. My current gut feeling though is, that if we stick to extend(s) we should probably keep the s for a better understanding of direction, as @petr.matas stated.

Thanks Lea!

As a note to T151301#3291681; the attribute "name" has usually no implication on uniqueness, but "id" has. To assume it is unique within a "group" seems consistent to me. If "name" shall be forced to be unique, then it would be better to change it to "id".