Look through the dominant {{reflist}} templates (name may vary) and reverse-engineer all functionality from the template documentation, template source, and any transcluded stylesheets.
- Choose wikis to study
- Top ten wikis by size
- RTL wikis
- Wikidata Q5462890 for sitelinks of Template:Reflist
- Global search for any template or module producing references
Functionality which is passed through the template to <references> will be omitted here when we already have parity. Examples:
- refs for list-defined references
- group. Note that some templates decouple predefined list marker styles from the "group".
- responsive. Most multicolumn implementations in reflist templates are now a facade in front of Cite responsive="1" plus minor CSS styling, but there are also some extra subfeatures which should be backported into Cite.
- Stylesheets like on enwiki are equivalent to global style overrides and were only attached to the template for encapsulation.
- Parameter validation.
Multicolumn is not omitted from the survey, but note that the Cite responsive feature already provides baseline parity.
- Migration was started in 2015, see T33597: Render references list in multiple columns based on the number of items.
- Note that the configuration variable $wgCiteResponsiveReferences sets the default value, it's not a feature flag. The feature is available on all sites.
- This could be ported to community configuration, which might also encourage more sites to enable it as default.
- Interesting that the default threshold of 10 is never overridden. This could be made into community configuration, but might not be appropriate to override on individual reflists?
Wikis reviewed
- enwiki
- {{reflist}}
- multicolumn
- TBD: columns are broken in template docs?
- predefined templates like {{notelist}} come with a default group name, which set the alphabet for its footnotes and are each paired with a specific {{efn}} variant.
- Possible misfeature: can override the footnote markers separately in reflist vs. article. "This should be used with care as it can be confusing to readers."
- Can ignore the unbalanced {{refbegin}} and {{refend}} wrap bibliographic-style citations, but never a reflist.
- frwiki
- {{références}}
- multicolumn
- Automatically change number of columns depending on namespace.
- Some templates add a tracking category when number of columns > 2
- Adds an element for CSS, div.reference-cadre
- TBD: what is tabindex="0" doing, it seems like a no-op?
- {{références nombreuses}} collapses using a scrolling frame. This is pure CSS, using height and overflow: auto.
- eswiki
- {{listaref}}
- multicolumn
- set symbols separately from group name
- arwiki
- Sometimes an explicit reflist div is included in wikitext, eg in this section.
- Uses unbalanced templates like {{بداية المراجع}} to open a div tag.
- Often doesn't use <references> at all!
- Multicolumn
- Hanging indent styling.
- Collapse to a scrolling box (pure CSS).
- {{مراجع}}
- Optionally switch containing element to dir=ltr
- Set symbol separate from group name
- fawiki
- {{پانویس}}
- multicolumn
- set symbol separately from group name
- hewiki
- {{הערות שוליים}}
- Container optionally rtl or ltr
- multicolumn
- svwiki
- Decided not to use the template in 2007. See discussion.
- nlwiki
- {{references}}
- multicolumn
- Translates the standard group names
- {{appendix}}
- Standardized section names
- {{references-scroll}}
- Collapse to a scrolling box
- ruwiki
- {{Примечания}}
- multicolumn
- set symbol separately from group name
- itwiki
- Decided not to use the template in 2017. See discussion.
- plwiki
- {{przypisy}} which calls Lua Module:Przypisy
- multicolumn (always)
- (Seems that the Lua module is only doing parameter validation.)
Summary of features
All existing functionality we've found in the wikis above can be reduced to these categories:
- CSS tweak. These may be applied globally to all reference lists, selected by choice of template, or configured by template parameter.
- Translation. Wikitext tag names are not currently localized, but template and parameter names can be.
Less commonly, the template extends beyond the reference list to its container: setting the section title and style, and suppressing the edit links. This is out of scope for our project. See T265753: The automatic <references/> list (when absent) should include an automatic heading above it for more discussion.
A full list of features, [TBD: and links to follow-up investigation]
- Multicolumn. Already have sufficient support in Cite responsive.
- RTL / LTR. More investigation needed, it's possible that Cite dir is already sufficient.
- Predefined configurations using a short name, eg. "{{references-scroll}}".
- Translated names, eg. "{{références}}".
- Footnote mark symbol, eg. "β". This is already implemented, but needs redesign to rationalize and consolidate.
- Collapsed list, scrolling in a fixed-height frame.
- Miscellaneous styling maybe not shared across many wikis.
Suggested reimplementations
Free styling
Pass through the class and style parameters. This is already an accepted pattern in wikitext, and a standard building block in HTML and component frameworks (eg vuejs).
Passing through data-* attributes as well would allow more sophisticated customization, which is still compatible with CSS selectors but allows for arbitrary extra information to be attached rather than just a yes/no class name boolean. For example, data-columns=2.
A suite of standardized reflist style tweaks can be bundled with Cite, for example "collapsed", "two-column", "greek". These can be applied one at a time or in combination.
Visual editor could expose these as checkboxes each toggling a class name, and a free text "class" attribute for additional user- or site-provided styles.
Community configuration could also expose these styles as checkboxes, but as a default to apply to all reflists. "no-" reverse styles should be provided to counteract these, eg. "no-collapsed".
Sites can override the bundled styles by adding more CSS rules for the class.
Free styling can be used to support the following features
- Multicolumn fine-tuning. The most common subfeature seems to be a parameter for column width. There should be some design work done to evaluate the tradeoffs for various screen and font sizes, vs. giving authors flexible layout options.
- Collapse to a scrolling box, with height and overflow. Some wikis such as enwiki have written policies discouraging collapsing because of accessibility issues. Any implementation of collapsing needs to solve these issues. Individual users can opt-in to collapsing styles in their personal overrides, of course.
- Arbitrary one-off, site-customized, styles.
- Forwards compatibility. Any template that passes through style and class attributes can be used in combination with existing or future styles. (To compare with a feature not compatible with generic styling: the responsive attribute requires explicit wiring between the template's multicolumn parameter and the responsive parameter.)
Tech breadcrumb: attributes can be wired in PHP using Sanitizer::fixTagAttributes, which converts an arbitrary string of user-provided attributes into a sanitized subset safe to reapply to the output.
See also, some unresolved discussion in T37704: Drop support in wikitext for inline styles about concerns with passing through styles.
Right-to-left
TBD: Work should continue independently, probably by improving the existing dir attribute.
Translation
Visual editor already works around this entire problem by hiding literal tag names from the user.
The translation problem is the same for all wikitext tags, and underlies much gratuitous template usage. T30980: parser tags such as <ref>, <poem>, <timeline> etc. cannot be localized
Predefined names—and the inevitability of templates
It seems likely that communities will still want to hold on to their templates, because of translation and to use predefined names for a set of styles, eg. "footnotes". Here I'll propose a minor tweak to TempateData which could help in that scenario:
Several new TemplateData parameter data types might come to the rescue here:
- "ref list" - Giving a parameter this type gives the visual editor a hint that it holds a collection <ref> tags which could be inspected and manipulated.
- "class" - ChipInput for boolean class names. If we find a reference list when introspecting the template output, we could even provide the reflist class presets...
- "style" - inline CSS, with validation that you're not using illegal rules or bad syntax.
Footnote symbols
The group name, choice of symbol alphabet, and whether or not to show the group name should be split into separate features. But they are intertwined so first we should better understand user needs.
There are divergent implementations of footnote symbols which need to be merged, in conjunction with T370027: [Epic] Parsoid CSS counter reset footnote/backlink mechanism should be dropped in favor of plain text:
- Literal symbol dynamically produced by Cite, for example "1", "2".
- MediaWiki messages with the entire sequence of symbols, for example lower-alpha.
- CSS list-style and counter-reset.
Community configuration should be provided to set the default and other predefined symbol sequences.
Visual editor could allow symbol customization for each reference list.
Make it impossible for the reflist marker style to be different than the footnote markers in the article. This probably means we should discourage any usage of CSS list-style, and always generate the markers explicitly in MediaWiki.
Suggested migration
Existing templates could be simplified incrementally, by pushing customizations into CSS and applying to all reflists or depending on a class name.
The shared, generalized styles should be provided through the Cite extension, before we ask communities to adapt. Ideally, the bundled styles can be used as-is, or if they are customized then this is done on top of a small set of known classes which simplifies future migrations.
Follow up
If necessary we can run the scraper to analyze usage frequency of specific features.
Follow up by roughly estimating the effort to reimplement each behavior in Cite for the <references> tag.
