Parsoid/Parser Unification/Cite CSS: Difference between revisions

Content deleted Content added

Inline

Revision as of 22:29, 25 January 2023

Like all extensions, the Cite extension has localized messages. However, a significant portion of the localized messages are for formatting and for localizing the numbering scheme.

Parsoid uses CSS to do the number-format-specific localization of the Cite extension. This approach ensures a good editing experience in editing clients like VisualEditor. 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.

Wikis should add appropriate CSS rules to their MediaWiki:Common.css file to ensure proper localization of citations in Visual Editor, given this difference in how citation number localization is done. This will become even more important as we start to migrate toward the use of Parsoid HTML for readers, not just for editing.

Which wikis are impacted?

Pretty much any wiki that uses localized numbering schemes for references is impacted. See Technical details for more details.

Is there a way to see if my wiki is impacted?

If you open a page that has citations in VisualEditor, and the citations on the page render differently from outside VE, then your wiki needs a fix. You either needs language-specific CSS rules (already addressed in T156350), or it needs CSS rules to be added to MediaWiki:Common.css.

Note that you this change may only be needed on pages with named references with multiple linkbacks, OR for pages that used reference groups (like lower-alpha, etc.).

Is there any help writing these CSS rules?

The Content Transform Team has written scripts to process language localization messages to programmatically generate CSS rules for a wiki's Common.css file. As part of visual diff testing, we have tested these rules and tweaked them a bit - mostly where the script couldn't get the CSS right to the last detail. You can see these rules here. For most wikis, these rules should work out of the box.

Verifying changes

Open a page in VisualEditor (after ensuring caches are purged) to see if the CSS fixes have improved the rendering of citations.

How do we plan to roll out these changes?

We would ideally like to see these changes rolled out everywhere by February 28, 2023.

Since this is primarily a change in how Cite localization is configured on wikis, the Content Transform Team is proposing to take on the task of adding the CSS rules to MediaWiki:Common.css on your wiki and verifying the changes. This might be especially beneficial to wikis that may not have the volunteer / technical resources available to roll out, test, and tweak the changes.

We will make an announcement on Tech News (and possibly other available venues as appropriate) with a link to this page and specifically, this proposal. If your wiki does not require direct assistance from us in implementing the changes, please add it to the list below. For these wikis, we are still around to assist and help, and we will follow up as appropriate to ensure these changes are made in a timely manner.

Wikis preferring to make changes on their own

If your wiki prefers to roll out and test these changes autonomously, please add it to the list below, along with your signature.

xxwiki - ~~~~
...
...

Reporting bugs

You can report bugs on Phabricator - please use the Parsoid or Parsoid-Read-Views tag to report your bugs.

Asking for help

You can reach out to the Content Transform Team by posting via the Talk page for this page. You may also be able to find us on IRC, but the talk page is probably the best place since the responses there might also help others.

@@ Line 1: / Line 1: @@
 Like all extensions, the Cite extension has localized messages. However, a significant portion of the localized messages are for formatting and for localizing the numbering scheme.
-Parsoid takes a different approach than the legacy parser and uses CSS to do the number-format-specific localization of the Cite extension. One of the reasons for this approach is to ensure a good editing experience in editing clients like VisualEditor. 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.
+Parsoid uses CSS to do the number-format-specific localization of the Cite extension. This approach ensures a good editing experience in editing clients like VisualEditor. 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.
 Wikis should add appropriate CSS rules to their <code>MediaWiki:Common.css</code> file to ensure proper localization of citations in Visual Editor, given this difference in how citation number localization is done.  This will become even more important as we start to migrate toward the use of Parsoid HTML for readers, not just for editing.
@@ Line 7: / Line 7: @@
 == Which wikis are impacted? ==
-Pretty much any wiki that uses localized numbering schemes will be impacted.
+Pretty much any wiki that uses localized numbering schemes for references is impacted. See [[Parsoid/Parser Unification/Cite CSS/Technical details|Technical details]] for more details.
+=== Is there a way to see if my wiki is impacted? ===
-There are three sources for localization:
+If you open a page  that has citations in VisualEditor, and the citations on the page render differently from outside VE, then your wiki needs a fix. You either needs language-specific CSS rules (already addressed in [[phab:T156350|T156350]]), or it needs CSS rules to be added to <code>MediaWiki:Common.css</code>.
-# Language-specific counters in MediaWiki core
-# Language-specific localization messages in the Cite extension repository
-# Message overrides defined in the <code>MediaWiki</code> namespace on the wiki.
+Note that you this change may only be needed on pages with named references with multiple linkbacks, OR for pages that used reference groups (like lower-alpha, etc.).
-Any wiki that uses localized numbers on wiki might be impacted. Additionally, any wiki using a language that provides a localized message for one of these Cite extension messages may need CSS rules for Parsoid HTML
-* cite_reference_link
-* cite_references_link_many_format
-* cite_references_link_many_format_backlink_labels
-* cite_references_link_one
-* cite_references_link_many
-* cite_references_link_many_sep
-* cite_references_link_many_and
-* messages with "Cite_link_label_group-" prefix.
-Example: For language <code>br</code> and message <code>cite_references_link_many_format</code>  in order to determine if your language is affected, you should check to see if <code>https://<your wiki>/wiki/MediaWiki:Cite_references_link_many_format</code> has non-default content; this should include both wiki-specific overrides as well as any defaults set in <code>i18n/<language code>.json</code> in the <code>Cite</code> extension repository.
-=== Localized language counters in MediaWiki core ===
-The Content Transform Team has addressed this via [[phab:T156350|T156350]] and these rules will be available for all these language wikis on all projects. We have [[gerrit:c/mediawiki/extensions/Cite/+/853079|defined language-specific counters]] that had localized counters defined in MediaWki and deployed them (E.g. [[gerrit:c/mediawiki/extensions/Cite/+/853079/8/modules/ext.cite.style.ar.css|arabic]], [[gerrit:c/mediawiki/extensions/Cite/+/853079/8/modules/ext.cite.style.bn.css|bengali]]).
-=== Localized Cite messages on a wiki ===
-Some wikis further localize citation formatting by using message overrides in the <code>MediaWiki</code> namespace on that wiki.
-Here is the list of 157 wikis that have some site message defined for Cite.
-{| class="wikitable"
-!Project
-!List of wikis
-|-
-|Wikipedia
-|acewiki, amwiki, arywiki, arzwiki, azbwiki, azwiki, be-taraskwiki, bgwiki, bjnwiki, bnwiki, bswiki, cewiki, ckbwiki, cswiki, cvwiki, dawiki, dewiki, eowiki, eswiki, euwiki, fawiki, frpwiki, frwiki, glwiki, guwiki, hewiki, hiwiki, hrwiki, idwiki, ilowiki, iuwiki, jvwiki, kawiki, kkwiki, kowiki, kuwiki, kvwiki, ladwiki, lnwiki, minwiki, mrwiki, mswiki, mtwiki, ndswiki, nowiki, nvwiki, ocwiki, pagwiki, rowiki, scnwiki, scowiki, shwiki, skwiki, slwiki, sqwiki, srwiki, suwiki, svwiki, testwiki, tgwiki, tiwiki, trwiki, urwiki, yiwiki, zhwiki, arwiki, fiwiki, huwiki, itwiki, jawiki, nlwiki, plwiki, ptwiki, ruwiki, ukwiki, viwiki, enwiki, bewiki, cawiki, cywiki, elwiki, etwiki, fowiki, hywiki, iswiki, ltwiki, lvwiki, mlwiki, mnwiki, newiki, nnwiki, orwiki, simplewiki, tawiki, thwiki, tlwiki, zh-yuewiki
-|-
-|Wikiquote
-|afwikiquote, enwikiquote, eswikiquote, glwikiquote, hewikiquote, hrwikiquote, itwikiquote, kawikiquote, ruwikiquote, sqwikiquote, ukwikiquote, viwikiquote
-|-
-|Wikisource
-|cswikisource, dewikisource, fiwikisource, frwikisource, glwikisource, hewikisource, hrwikisource, itwikisource, ruwikisource, vecwikisource, viwikisource, zhwikisource, eswikisource, plwikisource, wikisource, srwikisource
-|-
-|Wikitionary
-|bswiktionary, dewiktionary, enwiktionary, eswiktionary, frwiktionary, hrwiktionary, kuwiktionary, ocwiktionary, svwiktionary, trwiktionary, viwiktionary, zhwiktionary, gdwiktionary
-|-
-|Wikibooks
-|enwikibooks, glwikibooks, hewikibooks, jawikibooks, kawikibooks, nowikibooks, ruwikibooks, slwikibooks, viwikibooks
-|-
-|Wikinews
-|hewikinews, ukwikinews
-|-
-|Wikivoyage
-|ruwikivoyage, eswikivoyage, trwikivoyage
-|-
-|Affiliate wikis
-|ruwikimedia, uawikimedia
-|-
-|Other
-|metawiki, commons
-|}
-=== Is there a way to see if my wiki is impacted? ===
-Yes. If you open a page that has citations in VisualEditor, and the citations on the page render differently from outside VE, then your wiki either needs language-specific CSS rules (which we have handled via [[phab:T156350|T156350]] as above), or it needs CSS rules to be added to <code>MediaWiki:Common.css</code> which you will need to add. You can check whether your wiki has site-specific overrides in the <code>MediaWiki</code> namespace to determine if you need to add CSS rules in <code>MediaWiki:Common.css</code>.
 == Is there any help writing these CSS rules? ==
+The [[Content Transform Team]] has written scripts to process language localization messages to programmatically generate CSS rules for a wiki's Common.css file. As part of visual diff testing, we have tested these rules and tweaked them a bit - mostly where the script couldn't get the CSS right to the last detail. You can see '''[[gerrit:plugins/gitiles/integration/visualdiff/+/4864618d142551533f5b002c8d0b32217453428f/lib/parsoid.custom_styles.yaml|these rules here]]'''.  For most wikis, these rules should work out of the box.
-Yes, see below.
-=== Programmatically generated CSS rules ===
-The Content Transform Team has written scripts to process existing site messages and language localization messages to programmatically generate CSS rules for a wiki's Common.css file. As part of visual diff testing, we have tested these rules and tweaked them a bit - mostly where the script couldn't get the CSS right to the last detail. You can see '''[[gerrit:plugins/gitiles/integration/visualdiff/+/4864618d142551533f5b002c8d0b32217453428f/lib/parsoid.custom_styles.yaml|these rules here]]'''.  For most wikis, these rules should work out of the box.
 === Verifying changes ===

SSastry (WMF) (talk | contribs)