(In reply to comment #5)

You will become also problems with <ref> in infobox templates or so on, that
means you need another soluation than add a new tag or maintain a hardcoded
template list in VisualEditor.

I don't understand what you're saying? This is an enhancement about users frequently using a template to achieve a trivial software feature, and so building that into reference lists (<references />s) rather than having them need to invent and use the template.

Reference incidences (<ref>s) inside templates are an entirely distinct problem for VisualEditor to worry about, and this isn't about that. :-)

The references tag should support html attributes, than you can write <references class="***" /> and the template can be replaced.

Needs a set up a class for list-styles.

The extra class="reflist" is unneeded, because the references tag already adds class="references".

Thats why you can already add

.references { column-width: 35em; -moz-column-width: 35em; -webkit-column-width: 35em; }

to your common.css/user.css and all references will have column width, no need to tag each references tag with its own class.

But the template has the advanced, that syntax errors will not eat the rest of the page.

(In reply to comment #3)

Also, some wikis include more stuff in their reflist-like templates; for
example [[pl:Template:Przypisy]] unconditionally includes the heading.

Indeed. The equivalent template on Portuguese Wikipedia is also used to generate the header, and also has parameters to change the header text as well as its level (<h2>, <h3>, ...):
https://pt.wikipedia.org/wiki/Template:Referências

(In reply to comment #7)

I don't understand what you're saying? This is an enhancement about users
frequently using a template to achieve a trivial software feature, and so
building that into reference lists (<references />s) rather than having them
need to invent and use the template.

Reference incidences (<ref>s) inside templates are an entirely distinct
problem
for VisualEditor to worry about, and this isn't about that. :-)

This bug seems to be about enhancing <references /> so people won't (often?) have to embed <references /> in templates. However, I think db's point is that there are other reasons (besides {{reflist}}) that <references /> may be in a template. The example Bartosz gave (Carles Puyol) boils down (after a few template layers) to [[pl:Szablon:Infobox_uwagi_dodaj]], which has its own references tag with a custom infobox group. As shown at [[pl:Carles Puyol]], the effect is a small notes list just for the infobox.

The plwp infobox <references/> is here:
https://pl.wikipedia.org/wiki/Szablon:Infobox_uwagi_dodaj

What about the {{reflist}} variants on en.wiki such as {{notelist}}?

column-count is terrible indeed, especially for liquid layouts like in MediaWiki skins. When viewing it on a narrower window, it becomes unreadable.

column-width is a much more sensible approach, though I find it hard to believe either makes sense to be specified on the individual reflist. What I've seen in practice (at least on nl.wikipedia) that there is authors who know about it and explicitly use reflist with 2 columns in all their articles, and others who don't know about it, and others who prefer 3 for whatever reason.

The result is a chaos if different column counts per article.

When incorporating this back into the Cite extension, we can also provide a better default based on whatever really makes sense to derive it from. Whatever the rational is for needing multiple columns (mostly for readability I presume as the lines become too wide, and the list too long), we can automate that trivially based on rational UX arguments (yes, there shall be a global wiki bikeshed about why 2 is better than 3). Probably deriving it from the number of references in the list.

column-width will allow the list to fold back into 1 column on smaller devices and people who just like to narrow their window, and multiply out as the window gets wider. Of course this problem isn't entirely specific to references lists, it's also a long outstanding petpeeve of various designers about the article content itself, a fluid layout makes that content hard to read as well in some cases (though a fixed layout is probably better than multi-column in that case).

</brain-dump>

For the record, both column-count and column-width are fully automated CSS properties in the browser. It's 1 line of code to tell the browser, and then browsers handle it natively for us. No development on our side to split the list or anything like that.

Multiple columns for references causes two major usability issues:

1. When there is only one reference and this reference is longer than the column width, it is split into several parts, causing gaps inside the reference. This gets even worse for bidi texts: If you have a reference in a right-to-left language inside a left-to-right context, and it is split into multiple columns, you have to start reading on the right end of the left column, read to the left, jump right to the next column, read to the left again, etc.

2. When the list of references is longer than the screen and a reference breaks into two columns, you have to scroll to read it. This means:

a) You click the superscript number, the browser sends you to the upper part of the reference.
b) You have to scroll down to the beginning of the reference and start reading.
c) You have to scroll up again to the second part and continue reading.
d) If you don't know that you can use your browser's "back" function, you have to scroll down again to get to the back link.

Both issues could be solved by using "break-inside: avoid-column;", but the browser support currently is very poor. So unless browser support for this improves in future or somebody writes a JS solution for it, multi-column reference lists are a bad idea for usability reasons.

(In reply to comment #8)

The references tag should support html attributes, than you can write
<references class="***" /> and the template can be replaced.

This is bug 6019.

Needs a set up a class for list-styles.

Has anyone done an analysis of list-style usage on the large wikis? I am wondering whether Cite adding a class for the group name will suffice. (i.e. emitting class="references references-$group $invocationClassesVal")

I agree with others that Cite shouldn't add explicit support for columns, as this is very device-dependent; a class attribute indirectly provides this and more.

Can someone sum up exactly what has been agreed to do here?

(In reply to Alex Monk from comment #17)

Can someone sum up exactly what has been agreed to do here?

My understanding:

Do:

• Add a "column-width" optional property to the <references /> element, in ems, defaulting to unspecified => one column of 100% width.

• Ensure the issues about RTL display being logical are fix (you need to make sure that the columns and their contents both flow RTL).

• Make it look nice. :-)

• Should this default be variable as a per-wiki option?

• Add a "list-style" optional property to the <references /> element, an escaped pass-through of the CSS list-style of the OL, defaulting to decimal.

• Should this default be variable as a per-wiki/per-content-language option? I can imagine there might be better alternatives for some languages than "Arabic" Roman decimal.

Do not:

• Add a "columns" property (this breaks the concept of the Web's content being fit for any sized screen and shouldn't be encouraged).

• Add a new class to the <references /> OL – the "references" class can be over-ridden locally by wikis if they want to change it further.

Is this what others think?

Change 120962 had a related patch set uploaded by Alex Monk:
Support setting column-width and list-style in <references /> tag

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

IMO this should be a WONTFIX or LATER, and instead bug 6019 should be fixed.

What? We don't do LATER, and haven't for over a year.

Change 123093 had a related patch set uploaded by Alex Monk:
Support new column-width and list-style attributes to Cite's <references>

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

Change 123105 had a related patch set uploaded by Alex Monk:
Support new column-width and list-style attributes to Cite's <references>

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

Is there a good reason to use magic attributes and inline styles here instead of CSS classes? The latter is easier to customize for different environments and creates less complexity in the parsers (PHP and Parsoid).

All VE needs is a list of classes to offer in a drop-down or the like.

(In reply to Gabriel Wicke from comment #24)

Is there a good reason to use magic attributes and inline styles here
instead of CSS classes? The latter is easier to customize for different
environments and creates less complexity in the parsers (PHP and Parsoid).

All VE needs is a list of classes to offer in a drop-down or the like.

Your assertion that a restricted set of classes invented by the development team will be sufficient for the community's existing wishes to be fulfilled is not met by reality…

See https://gerrit.wikimedia.org/r/#/c/120962/ for more discussion on this.

Change 123105 abandoned by Alex Monk:
Support new column-width and list-style attributes to Cite's <references>

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

Change 120962 abandoned by Alex Monk:
Support setting column-width and list-style in <references /> tag

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

Change 123093 abandoned by Alex Monk:
WIP Support new column-width & list-style attributes to Cite's <references>

Reason:
Abandoning all related patch sets

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

No. We /are/ going to do this. Gabriel is on the hook for suggesting how to do it in a way that makes him happy, given he vetoed the agreed way. It certainly isn't "UNCONFIRMED".

Bug 22265 - Allow references to be listed with letters

Change 120962 restored by Alex Monk:
Support setting column-width and list-style in <references /> tag

Reason:
Going to use classes.

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

Change 123093 restored by Alex Monk:
WIP Support new column-width & list-style attributes to Cite's <references>

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

Change 123105 restored by Alex Monk:
Support new column-width and list-style attributes to Cite's <references>

Reason:
Restoring so I can do a rebase to get the VE patch working

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

I picked up the Cite & VE parts of this again.

Change 123105 abandoned by Alex Monk:
Support new column-width and list-style attributes to Cite's <references>

Reason:
ok done

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

See also:
Bug 31597 - generate class for references list according to the number of refs

I fail to see how it is in anyone's best interest to implement support for list-style and column sizes on an individual <references> list.

These are traditionally implemented in a {{reflist}} template on Wikipedia. That was by all accounts a compromise due to the limited capability they have inside a template. What people want is for stuff to just work. They don't actually want to specify it manually each time.

Adding this to the extension will improve nothing other than move it from a template hack to something we now have to support and maintain forwards.

There has yet to be given a valid reason for why anyone would explicitly, semantically, by intent, want one specific article to have its references in a certain number of columns or certain list item number style.

The number of columns should be determined by width, not hardcoded count. And while the latest patch uses width, it is still imho fundamentally flawed. Users don't want to hardcode this everywhere (authors will not know this even exists, leading to generally no single user actually using this feature other than power users, whom then have to write bots that fix it everywhere; or more likely, they'll just use another template that specified the width and list-style they agree on for that wiki).

If this were any other feature, it'd be obvious this is something for the software to provide as a convenience. Not a burden for the users. Based on design considerations, can make a reasonable choice for what the column width should be. And it can be improved as we collect more data and positively influence all readers.

While there may not be a perfect value, I know for sure the factors that make it less perfect don't vary by article. They vary by device, browser, etc. It will traditionally and up with authors using their personal preference for what looks right on their device.

The only thing that is probably in need of variation is list-style (based on content language), which, again, seems like something we can be much smarter about. If there isn't a way to get that already from the Language infrastructure, we can provide a config variable or mediawiki-message specifying the list-style for that wiki or language. One exception could be multi-lingual wikis, so maybe provide list-style as attribute indeed.

Note: Gabriels proposal for css classes is imho better than providing a hardcoded column-width, but per the above, we don't need either.

Just to make this clear (since I was told to say this here rather than in Gerrit): 100% agree to what Krinkle and Gabriel said. See bug 31597 (T33597) for a much more elaborate proposal.

@thiemowmde mentions T33597

It should be noted that mobilefrontend already does some CSS overrides here (setting a default column width).

This was discussed at the weekly meeting on 2015-06-30. We decided that it wasn't a priority for this quarter.

For VisualEditor, we are continuously-bitten by <references /> tags that are embedded within generated content like the English Wikipedia's {{reflist}} (T52769). It would be much easier for everyone if we just moved the features provided by such templates into the Cite extension itself and allowed such templates to be replaced by the now more powerful <references /> tag.

Reference incidences (<ref>s) inside templates are an entirely distinct problem for VisualEditor to worry about, and this isn't about that. :-)

You're contradicting yourself, chuckle. I agree with the second statement, fixing VisualEditor's difficulties with templates is bug T52769. This proposal of a more powerful more powerful <references /> tag isn't going to help that bug because communities will still have various reasons for putting things inside various templates. If that's the purpose of this bug, it's a failure when it still gets templated.

This bug really only makes sense in light of something like T33597: Render references list in multiple columns based on the number of items which aims to add useful new functionality regardless of whether it's put inside a template.

FYI, I've added some support to en.wp's {{reflist}} to explicitly enable and disable automatic columns.
Next step for en.wp will be to enables responsive by default for a plain <references> element

This leaves the following capabilities that are specific to Reflist, which currently cannot be fulfilled with a plain references element

1. Different list item counters
2. Differing column widths (this one is also not really compatible with automatic columns, which will create a bit of a disjunct in behaviour).

This doesn't negate the fact that:

• of course reflist is already universally used, and universally changing it will probably be seen as disruptive.
• there is also a rather large documentation gap, atm. regarding new and old information.
• ironically, it seems that the responsive attribute cannot be set/unset from VE

An idea that played in my mind, which would be terribly WMF specific, but might make it easier to work with this problem, is if we should maybe change the VE editor of <references/> and the Template:Reflist, to be aware of each other, and maybe offer the opportunity to switch between them ("more options", vs "convert to references element"). Just a thought.

Change 378935 had a related patch set uploaded (by Esanders; owner: Esanders):
[mediawiki/extensions/Cite@master] VE: Support 'responsive' attribute

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

Change 378935 merged by jenkins-bot:
[mediawiki/extensions/Cite@master] VE: Support 'responsive' attribute

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