Refactor {{CSSXref}} for ease of reference to CSS functions and descriptors

[yarusome]

Note: There's a thematically similar discussion, but this discussion focuses on {{CSSXref}} and attempts to materialize its refactoring due to the simpler structure of CSS pages (before this discussion gets momentum again). For anyone that has read the first discussion, the first section below can be skipped.

---

Many CSS functions now reside under a CSS data type, e.g:

• rgb() is under <color>;
• linear-gradient() is under <gradient>.

Apart from this, all descriptors are under their respective ar-rules, e.g:

• font-display is under @font-face.
• prefers-color-scheme is under @media.

To refer to these functions and descriptors per current page structures using {{CSSXref}}, it's necessary to use a rather repetitive invocation like {{CSSXref("color_value/rgb", "rgb()")}}, which almost defeats the purpose of the macro.

---

Therefore, I propose to refactor {{CSSXref}} as below:

1. No change for CSS functions right under /CSS, e.g. abs().

   Note: (1) Currently {{CSSXref("abs()")}} would generate a link pointing to https://developer.mozilla.org/en-US/docs/Web/CSS/abs(), and the extraneous parentheses in the URL needs removing. (2) {{CSSXref("fit-content()")}} fails to be handled correctly like the way <color> is. See fix(macros/cssxref): correct URL generation for data types and functions yari#8766.

2. For any invocation with a single parameter containing /, set the link text as the content after /. If page-type is css-function, postfix with parentheses.

   This means the following change to {{CSSXref}} on Line 34:

   - var displayName = ($1 || $0);
   + var displayName = ($1 || $0.slice($0.lastIndexOf("/") + 1));

   Note: (1) Postfixing is gracefully handled by existing Line 62 to 64. (2) lastIndexOf() is used future-proof instead of indexOf().

---

If there's consensus on moving forward, I'd be happy to open a PR in mdn/yari.

[wbamberg]

Sounds like a good idea to me! I wonder if there are currently any instances of a single parameter containing "/". It sounds unlikely.

I mean, I would obviously prefer it if we had a sensible hierarchy for CSS, but since that discussion isn't going anywhere... 🤷 .

[yarusome]

/{{ *CSSXref\("[^"/]*/[^"/]*"\) *}}/gi yields 16 occurrences on 7 pages:

• Firefox 44 for developers
  • {{cssxref("@page/marks")}}
• Firefox 91 for developers
  • {{cssxref("@counter-style/pad")}}
• Firefox 92 for developers
  • {{cssxref("@font-face/size-adjust")}}
• FontFace: ascentOverride property (×2)
  • {{cssxref("@font-face/ascent-override")}} (×2)
• FontFace: descentOverride property
  • {{cssxref("@font-face/descent-override")}}
• FontFace: FontFace() constructor (×9)
  • {{cssxref("@font-face/ascent-override")}}
  • {{cssxref("@font-face/descent-override")}}
  • {{cssxref("@font-face/font-display")}}
  • {{cssxref("@font-face/line-gap-override")}}
  • {{cssxref("@font-face/font-stretch")}}
  • {{cssxref("@font-face/font-style")}}
  • {{cssxref("@font-face/unicode-range")}}
  • {{cssxref("@font-face/font-variation-settings")}}
  • {{cssxref("@font-face/font-weight")}}
• FontFace: lineGapOverride property
  • {{cssxref("@font-face/line-gap-override")}}

---

It seems pretty safe to left these invocations as they are during the refactoring.