Cite: Support multi-column and alternative list-style for <references /> tag (like enwiki {{reflist}})
OpenPublic

Description

For VisualEditor we are continuously-bitten by <references /> tags that are embedded within generated content (generally, enwiki's {{reflist}} but some other wikis have duplicated it.

It would be much easier for everyone if we just moved this widely-demanded feature into Cite itself as HTML-like attributes on the extension tag, and the templates were deprecated.

This would involve adding:

  • columns (default to 1; a number between 1 and … another number? - not allowing width, obviously)
  • list-style (default to decimal; just an escaped pass-through of the CSS list-style of the OL)

Then we could just bot-substitute uses of the template, and everyone would be happy.


Version: master
Severity: enhancement
See Also: T53145, T47132, T8019, T56906, T33597

bzimport added a project: Cite.Via ConduitNov 22 2014, 1:50 AM
bzimport set Reference to bz51260.
Jdforrester-WMF created this task.Via LegacyJul 12 2013, 8:57 PM
matmarex added a comment.Via ConduitJul 12 2013, 9:10 PM

(In reply to comment #0)

  • columns (default to 1; a number between 1 and … another number? - not allowing width, obviously)

"Obviously"? In my opinion setting maximalcolumn width and letting the browser figure out the layout makes more sense than hardcoded number (although sadly it's not how it's done right now).

  • list-style (default to decimal; just an escaped pass-through of the CSS list-style of the OL)

That would be a bad way to do this; the list style should actually depends on the group name used (since Cite has a way to provide custom markers instead of [1] to reference citations, list-style is used to match them - see [[Special:PrefixIndex/MediaWiki:Cite_link_label_group]] for ones defined on en.wp).

Jdforrester-WMF added a comment.Via ConduitJul 12 2013, 9:17 PM

(In reply to comment #1)

(In reply to comment #0)
> * columns (default to 1; a number between 1 and … another number? - not
> allowing width, obviously)

"Obviously"? In my opinion setting maximalcolumn width and letting the
browser figure out the layout makes more sense than hardcoded number (although
sadly it's not how it's done right now).

We should be reducing, not increasing, the use of hard-coded widths. HTML is not a graphical layout language, and should not be bastardised to serve as such.

> * list-style (default to decimal; just an escaped pass-through of the CSS
> list-style of the OL)

That would be a bad way to do this; the list style should actually depends on
the group name used (since Cite has a way to provide custom markers instead
of [1] to reference citations, list-style is used to match them - see
[[Special:PrefixIndex/MediaWiki:Cite_link_label_group]] for ones defined on
en.wp).

Sorry, yes, I meant "default to what the group states; if no group, default to decimal; otherwise, let the user over-ride".

matmarex added a comment.Via ConduitJul 12 2013, 9:23 PM

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

(In reply to comment #2)

> "Obviously"? In my opinion setting maximalcolumn width and letting the
> browser figure out the layout makes more sense than hardcoded number (although
> sadly it's not how it's done right now).

We should be reducing, not increasing, the use of hard-coded widths. HTML is
not a graphical layout language, and should not be bastardised to serve as
such.

Hardcoding the number of columns is the same, except worse, since it can't be adjusted to the capabilities of the browser/device without violating CSS spec.

CSS only allows specifying column width "hints", anyway, and they can be measured in ems. https://developer.mozilla.org/en-US/docs/Web/CSS/column-width

Jdforrester-WMF added a comment.Via ConduitJul 12 2013, 9:37 PM

(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.

(In reply to comment #2)
> > "Obviously"? In my opinion setting maximalcolumn width and letting the
> > browser figure out the layout makes more sense than hardcoded number
> > (although sadly it's not how it's done right now).
>
> We should be reducing, not increasing, the use of hard-coded widths. HTML is
> not a graphical layout language, and should not be bastardised to serve as
> such.

Hardcoding the number of columns is the same, except worse, since it can't be
adjusted to the capabilities of the browser/device without violating CSS
spec.

CSS only allows specifying column width "hints", anyway, and they can be
measured in ems.
https://developer.mozilla.org/en-US/docs/Web/CSS/column-width

OK, then I suppose we should maintain equivalence with {{reflist}} here.

duplicatebug added a comment.Via ConduitJul 13 2013, 7:20 AM

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.

matmarex added a comment.Via ConduitJul 13 2013, 9:52 AM

(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.

Hm, yeah, I didn't think about it, but some infoboxes include their own <ref>s *and* <references group=.../>, for example pl.wp infoboxes for football players and some other sportsmen; an example can be seen on [[pl:Carles Puyol]].

Jdforrester-WMF added a comment.Via ConduitJul 13 2013, 2:08 PM

(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. :-)

duplicatebug added a comment.Via ConduitJul 13 2013, 7:38 PM

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.

He7d3r added a comment.Via ConduitJul 13 2013, 8:18 PM

(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

Mattflaschen added a comment.Via ConduitJul 14 2013, 12:41 AM

(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.

jayvdb added a comment.Via ConduitJul 14 2013, 1:15 AM

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

Gadget850 added a comment.Via ConduitAug 28 2013, 5:02 PM

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

Krinkle added a comment.Via ConduitSep 27 2013, 9:06 AM

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>

Krinkle added a comment.Via ConduitSep 27 2013, 9:10 AM

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.

Schnark added a comment.Via ConduitOct 30 2013, 11:27 AM

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.
  1. 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.

jayvdb added a comment.Via ConduitOct 30 2013, 12:28 PM

(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.

Krenair added a comment.Via ConduitMar 6 2014, 5:50 PM

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

Jdforrester-WMF added a comment.Via ConduitMar 13 2014, 4:12 PM

(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?

gerritbot added a comment.Via ConduitMar 25 2014, 11:16 PM

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

jayvdb added a comment.Via ConduitMar 26 2014, 2:25 AM

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

Krenair added a comment.Via ConduitMar 26 2014, 6:26 PM

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

gerritbot added a comment.Via ConduitApr 1 2014, 9:20 PM

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

gerritbot added a comment.Via ConduitApr 1 2014, 9:44 PM

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

GWicke added a comment.Via ConduitApr 1 2014, 9:57 PM

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.

Jdforrester-WMF added a comment.Via ConduitMay 30 2014, 8:44 PM

(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…

GWicke added a comment.Via ConduitMay 30 2014, 9:46 PM

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

gerritbot added a comment.Via ConduitJul 19 2014, 2:41 PM

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

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

gerritbot added a comment.Via ConduitJul 19 2014, 2:41 PM

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

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

gerritbot added a comment.Via ConduitJul 19 2014, 2:42 PM

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

Jdforrester-WMF added a comment.Via ConduitJul 19 2014, 4:34 PM

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".

Gadget850 added a comment.Via ConduitJul 21 2014, 11:09 PM

Bug 22265 - Allow references to be listed with letters

gerritbot added a comment.Via ConduitSep 3 2014, 10:13 PM

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

gerritbot added a comment.Via ConduitSep 3 2014, 10:13 PM

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

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

gerritbot added a comment.Via ConduitSep 4 2014, 12:46 AM

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

Krenair added a comment.Via ConduitSep 4 2014, 12:49 AM

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

gerritbot added a comment.Via ConduitSep 4 2014, 12:53 AM

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

Gadget850 added a comment.Via ConduitSep 24 2014, 9:42 AM

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

Krinkle added a comment.EditedVia ConduitOct 7 2014, 10:57 PM

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.

thiemowmde added a comment.EditedVia ConduitOct 8 2014, 9:21 AM

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.

fbstj edited the task description. (Show Details)Via WebNov 24 2014, 1:06 PM
fbstj set Security to None.
fbstj added a subscriber: fbstj.
Jdforrester-WMF moved this task to Doing on the Cite workboard.Via WebDec 1 2014, 9:02 PM
duplicatebug removed a subscriber: duplicatebug.Via WebDec 13 2014, 11:29 AM
TheDJ added a subscriber: TheDJ.Via WebMar 2 2015, 3:42 PM

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

Krenair placed this task up for grabs.Via WebThu, Apr 2, 3:36 AM
Krenair removed a project: Patch-For-Review.

Add Comment

Column Prototype
This is a very early prototype of a persistent column. It is not expected to work yet, and leaving it open will activate other new features which will break things. Press "\" (backslash) on your keyboard to close it now.