Last modified: 2014-11-07 15:32:46 UTC
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.
(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.
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. -- Gabriels proposal for css classes is imho better than providing a hardcoded column-width, but per the above, we don't need neither.
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 for a much more elaborate proposal.
