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

Description

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.

Points of agreement include:

  • The main requirements are for <references /> to support multiple columns and different list styles
    • T33597 discusses defaulting to multiple columns for all reference lists
  • Columns should be implemented using column widths rather than column counts, to allow flexibility based on screen size.

This task is currently blocked, on the following issues:

  • What the default settings/algorithms should be
  • Whether column widths and list styles should be customizable per-page, or only per-wiki
  • If per-page customizations are allowed, whether they should be implemented by passing through CSS properties from the invocation of the <references /> tag or by applying CSS classes, which are then given CSS properties on a per-wiki or global level.

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.

See Also: T53145, T8019

bzimport set Reference to bz51260.

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

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

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

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

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.

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

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

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

(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

GWicke added a comment.Apr 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.

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

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

Krinkle added a comment.EditedOct 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.EditedOct 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)Nov 24 2014, 1:06 PM
fbstj set Security to None.
fbstj added a subscriber: fbstj.
Jdforrester-WMF moved this task from Backlog to Doing on the Cite board.Dec 1 2014, 9:02 PM
TheDJ added a subscriber: TheDJ.Mar 2 2015, 3:42 PM

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

Krenair removed Krenair as the assignee of this task.Apr 2 2015, 3:36 AM
Krenair removed a project: Patch-For-Review.
Harej awarded a token.May 10 2015, 3:05 AM
marcoil removed a subscriber: marcoil.Jun 17 2015, 7:11 AM

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

Jdforrester-WMF moved this task from Doing to Next-up on the Cite board.Aug 3 2015, 2:39 AM
Jdforrester-WMF lowered the priority of this task from "High" to "Normal".
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptAug 3 2015, 2:39 AM
Jdforrester-WMF moved this task from Doing to Next-up on the Cite board.Aug 3 2015, 2:40 AM
Jdforrester-WMF lowered the priority of this task from "High" to "Normal".
Alsee added a subscriber: Alsee.Nov 8 2015, 9:24 AM

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.

fbstj awarded a token.Dec 15 2015, 2:55 PM
fbstj removed a subscriber: fbstj.

Add Comment