Page MenuHomePhabricator

[Epic] Parsoid CSS counter reset footnote numbering mechanism should be dropped in favor of plain text
Open, Needs TriagePublic

Description

Instead of emitting a CSS counter-reset for each footnote marker, Parsoid should emit literal text such as [3] or [٣], according to content language and custom group configuration. This is already how the legacy parser works.

Many sites are using CSS customizations for these numbers, and this must be considered during migration to explicit numbering. When this epic is complete, the customizations should be removed. The big relief here is that custom groups already need to be customized using all mechanisms, so we can rely on eg. the i18n message being available. Example custom group labels: fa:MediaWiki:Cite link label group-persian-alpha

Motivations:

  • Makes it possible to do localization and alternative counter markers along with programmatic document rendering.
  • Consolidate to a single mechanism.
  • Plaintext compatibility (eg. copy and paste).
  • Consistency in VE (TBD: explain in more detail)
  • Prerequisite implement subreferencing

Historical notes:

  • The legacy Cite parser has always used explicit numbering.
  • CSS counter-reset numbering was first introduced into Parsoid in T86782: Use CSS to style Parsoid's Cite extension output to work around customization. At the time, Parsoid was written in JS and couldn't conveniently tap into the PHP i18n which provides custom numbering.

Out of scope: some related tasks will be implemented separately. Experience gained during this task can be applied to the other issues, we'll refine the other tasks' descriptions to add this info.

Related Objects

Event Timeline

You might want to take a look at https://www.mediawiki.org/wiki/Parsoid/Parser_Unification/Cite_CSS from a year or two ago. And the subpage https://www.mediawiki.org/wiki/Parsoid/Parser_Unification/Cite_CSS/Technical_details . CSS was mass-added in many Common.css pages to support this.

You might want to take a look at https://www.mediawiki.org/wiki/Parsoid/Parser_Unification/Cite_CSS from a year or two ago. And the subpage https://www.mediawiki.org/wiki/Parsoid/Parser_Unification/Cite_CSS/Technical_details . CSS was mass-added in many Common.css pages to support this.

Thanks for the extremely helpful links!

It does seem that we're coming into the discussion a bit too late. The premise behind the CSS work is flawed, unfortunately:

When citations are modified (added / removed), using CSS ensures that the numbers adjust automatically and consistently. Otherwise, VE (and other clients) would have to make a server request to re-render all citations each time one is added or removed which can make for a poor and inefficient experience.

My understanding is that CSS is incapable of making numbering decisions by itself and therefore VE needs to actively renumber refs in client JS, so both "have to make a server request" and "CSS adjusts automatically" are incorrect. As a simple example, consider the case of ref reuse: "A[1], B[2], C[1]". There is no mechanism available to automatically give the "C" statement ref the same number as the "A" statement has, other than to recalculate all refs from JavaScript.

We know this is an issue. We'll soon schedule a talk with WMDE to go over this.

Change #1055504 had a related patch set uploaded (by Awight; author: Awight):

[mediawiki/extensions/Cite@master] [refactor] finish abstracting the parsoid language style overrides

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

Change #1055504 merged by jenkins-bot:

[mediawiki/extensions/Cite@master] [refactor] finish abstracting the parsoid language style overrides

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

My memory of recent conversations on the topic is that we eventually decided in favor of explicit numbering and to phase out the CSS counter-reset approach. If you don't mind, it would be great to have a Parsoid team countersign of that decision so that people watching this task can be sure of the outcome.

My memory of recent conversations on the topic is that we eventually decided in favor of explicit numbering and to phase out the CSS counter-reset approach. If you don't mind, it would be great to have a Parsoid team countersign of that decision so that people watching this task can be sure of the outcome.

+1

That seems right, as long there are not objections to the initial documentation we sent, you should be able to proceed without blockers.

This task will be split into smaller bits for implementation now.

awight renamed this task from Parsoid CSS counter reset footnote numbering mechanism should be dropped in favor of plain text to [Epic] Parsoid CSS counter reset footnote numbering mechanism should be dropped in favor of plain text.Oct 29 2024, 12:58 PM