Page MenuHomePhabricator

Find a good name for new attribute in ref tag
Closed, ResolvedPublic2 Estimated Story Points

Description

To implement T151301, we need a name for an extension attribute.

Things to take into consideration

  • it should make clear what it stands for ("We want to further specify a reference, which is the following one")
  • it should make clear which direction we are talking about (is it extending or being extended?)
  • naming scheme should fit to existing params. We have "name", "follow", "group"....

Current ideas

  • extend(s)
  • parent
  • refine(s)
  • base
  • using
  • for
  • at

Result
The TechWish team evaluated more than 20 ideas for an attribute name. Criteria for this evaluation were:

  • Is the meaning of the attribute obvious?
  • Does the source code read (almost) like a sentence?
  • Is the language accessible?
  • Is it easy to use?

Two attribute names fulfilled these criteria equally well: extends and using.
The team chose extends because, on top of fulfilling the criteria well, it's been part of the discussion already. usingon the other hand is a new suggestion and has not been discussed.

More details can be found in this decision matrix: https://docs.google.com/spreadsheets/d/1_BLOBW38BcdrHzInEqrfdpFJXAETsx-uJKr5V264ZJg/edit?usp=sharing

Event Timeline

Izno updated the task description. (Show Details)Jul 25 2017, 1:41 PM

The original proposal was for "refines" and was changed to "extends" later without discussion. I've added that as an option.

petr.matas added a comment.EditedJul 26 2017, 4:08 AM

(Obsoleted by T171581#4568792)
My favorites in the order of preference (best first):

  1. parent
  2. refines (definitely with -s to indicate direction)
  3. extends (definitely with -s to indicate direction)

The only argument i know that is contra "refines" is that it is very close to "ref": <ref refines="…">…</ref>.

On the pro site, I find "refines" explains very much exactly what happens.

I find both "extends" and "parent" very much problematic, especially because they are already used in all kinds of object oriented languages. What "extends" does to two <ref> is not the same as what "extends" does to two classes:

  • There is no way to interact with the parent.
  • There is no overloading or something like that. There is only appending.
  • You can not extend something that was already extended, which is very much unexpected.

Please stick to "refines".

I don't know if you're looking for more ideas (I only saw this scrolling by on IRC), but there's a lot more words that could be used.

I think both extend(s) and refine(s) do not make it clear whether this affects others uses of this reference (at the very least, I had to look at the parent tasks to figure out what you're implementing).

Ideas:

  • <ref base="…">…</ref>
  • <ref using="…">…</ref>

Also – given that these are still not translateable in the year 2017 (really…?), I think it would be valuable to choose a name more likely to be familiar to non-native English speakers. So I would vote againts "refine"/"refines" :(

Lea_WMDE updated the task description. (Show Details)Aug 17 2017, 3:47 PM
jeblad added a comment.EditedSep 14 2017, 2:46 PM

The usual wording for an attribute that make an element depend on something else is "for". The attribute "for" would then hold the id of the other element. Because the name is used as the id, if no explicit id exists, then "for" would hold the name. The group must also be specified as the name is only unique within a group. No explicit group attribute imply using a default group.

That means

Ping is foo.<ref name="ex">Stuff for a complete reference</ref>
Yet Pong is bar.<ref for="ex">Additional stuff</ref>

Unfortunately this does not make it clear how the surface rendering will reorder the references, or the purpose of the second reference. The order of dependency will although be clear, and also the expected behavior, which is perhaps more important.

jeblad added a comment.EditedSep 14 2017, 2:51 PM

On T171581#3531014, I believe it is a really bad idea to translate tag functions. Actually I believe it is a really bad idea to translate all such markup and programming constructs without a working translator for those constructs.

Izno added a comment.EditedSep 14 2017, 4:37 PM

On T171581#3531014, I believe it is a really bad idea to translate tag functions. Actually I believe it is a really bad idea to translate all such markup and programming constructs without a working translator for those constructs.

Try not to get wrapped around that here; the task of interest for translation of parser tags is T30980: parser tags such as <ref>, <poem>, <timeline> etc. cannot be localized.

The usual wording for an attribute that make an element depend on something else is "for". The attribute "for" would then hold the id of the other element.

For is another reasonable name, but I don't prefer it given its connotation.

jeblad updated the task description. (Show Details)Sep 15 2017, 5:44 PM
Dereckson updated the task description. (Show Details)Apr 1 2018, 3:10 PM
Addshore removed a subscriber: Addshore.Apr 3 2018, 9:07 AM

Hi! The question of naming is also a part of this feedback round on Meta. Feel free to comment, discuss and spread the word! The round closes on May 27th, 2018.

After seeing the new proposals I changed my order of preference a bit:

  1. parent - maybe slightly less known than base, but still very good. Clearly indicates the direction (parent of this is ...). Object-Oriented Programmers may say that this is not inheritance, but rather association. However, it is clear what is going on here, because writing is not programming.
  2. base - very simple noun, known to most non-English speakers. OOP considerations as above.
  3. extends (definitely with -s to indicate direction) - not a noun and therefore not a good name.
  4. refines (definitely with -s to indicate direction) - the same as above and unknown to many non-English speakers.
  5. using - not a noun
  6. for - not a noun, confusing. I would expect such attribute to identify the text being sourced by this reference
  7. sub... - anything with sub in it suggests the wrong direction: The attribute refers to the parent, not to the child.
Izno updated the task description. (Show Details)Nov 7 2018, 8:36 PM

I suggest to put the list of candidates[1] on a whiteboard, together with all the criteria we find relevant. By discussing the criteria and ordering them by relevance, we should be able to cross-out candidates, until we are left with only one.

Possible criteria:

  • Are multi-word attributes like is-child or isChild even an option?
  • Can we make it obvious that users do not need to repeat the content of the original <ref>? Or the other way around: Do some words sound like you need to repeat the content from the original <ref>?
  • Some words might sounds more like the original <ref> is replaced/overridden. But what we do is creating a child that typically does not make any sense without it's parent being visible.
  • Can we pick a word that makes the direction (parent → child) more obvious?
  • Can we avoid confusion with existing attributes? (As of now these are name, group, follow, and dir.)
  • How critical is it to avoid confusion with the tag <ref> itself?

[1] From https://meta.wikimedia.org/wiki/WMDE_Technical_Wishes/Book_referencing/Call_for_feedback_(May_2018)#For_wikitext_users:_Which_name_do_you_prefer_for_the_attribute_within_the_%3Cref%3E_tag%3F:

  • # (<ref name="base#2">Page 2</ref>)
  • at (<ref name="base" at>Page 2</ref> or <ref name="base" at="Page 2" />)
  • base
  • def
  • extend
  • extends
  • for
  • loc
  • locates
  • parent
  • ref
  • refine
  • refinement
  • refines
  • spec
  • specifies
  • sub
  • subname (<ref name="base" subname="base2">Page 2</ref>)
  • subref
  • using

To do:

It's a draft at the moment. We are going to make it public after the meeting happened.

awight added a subscriber: awight.

We need to document the decision taken and methodology.

Bmueller removed a subscriber: Bmueller.Nov 6 2019, 12:47 PM
awight set the point value for this task to 2.

Change 550435 had a related patch set uploaded (by Awight; owner: Awight):
[mediawiki/extensions/Cite@master] Rename refines -> extends

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

Change 550435 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] Rename refines -> extends

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

JStrodt_WMDE closed this task as Resolved.Nov 12 2019, 11:03 AM
JStrodt_WMDE updated the task description. (Show Details)