Page MenuHomePhabricator

Find a good name for new attribute in ref tag
Open, NormalPublic

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

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