Content: [Markdown] Decide what to do about <sup> and <sub>

[wbamberg]

In the JS docs we use <sup> and <sub>. There isn't an equivalent of these in GFM.

How much is it used?

• <sup>: 127 occurrences across 44 files:

https://developer.mozilla.org/en-us/web/javascript/a_re-introduction_to_javascript
https://developer.mozilla.org/en-us/web/javascript/about_javascript
https://developer.mozilla.org/en-us/web/javascript/data_structures
https://developer.mozilla.org/en-us/web/javascript/guide/control_flow_and_error_handling
https://developer.mozilla.org/en-us/web/javascript/guide/expressions_and_operators
https://developer.mozilla.org/en-us/web/javascript/guide/indexed_collections
https://developer.mozilla.org/en-us/web/javascript/guide/numbers_and_dates
https://developer.mozilla.org/en-us/web/javascript/language_resources
https://developer.mozilla.org/en-us/web/javascript/reference/errors/invalid_array_length
https://developer.mozilla.org/en-us/web/javascript/reference/errors/resulting_string_too_large
https://developer.mozilla.org/en-us/web/javascript/reference/functions/rest_parameters
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/array
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/every
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/foreach
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/from
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/length
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/some
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/array/splice
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/bigint/asintn
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/bigint/asuintn
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/bigint
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/date/now
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/date/parse
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/date/utc
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/function/apply
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/function/bind
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math/exp
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math/expm1
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math/hypot
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math/pow
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math/random
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/number/epsilon
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/number
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/number/issafeinteger
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/number/max_safe_integer
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/number/max_value
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/number/min_safe_integer
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/object/tostring
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/parseint
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/string/fromcharcode
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/typedarray
https://developer.mozilla.org/en-us/web/javascript/reference/operators/bitwise_not
https://developer.mozilla.org/en-us/web/javascript/typed_arrays

• <sub>: 14 occurrences across 3 files:

https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/math
https://developer.mozilla.org/en-us/web/javascript/reference/global_objects/string/fromcharcode
https://developer.mozilla.org/en-us/web/javascript/reference/operators/operator_precedence

They're usually used in math expressions in the JS docs, for example:
https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/bigint/asuintn#returns
https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/math/pow
https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/array/length#description

They're sometimes used to write things like 5^th:
https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/array/every#polyfill

What should we do?

Two options:

Option 1: use <sup> and <sub> in the source

This would be OK I think. These tags aren't very widely used, they tend to be used for specialised things, and they are self-contained - they don't pollute big chunks of the page in the way that using HTML <dl> or <table> does. That is, you can write **blah<sup>123</sup>** and it renders fine.

Option 2: use Unicode superscript/subscript characters

You can get superscript and subscript just by using the appropriate Unicode characters: https://en.wikipedia.org/wiki/Superscripts_and_Subscripts_(Unicode_block). It looks like this will work for all the numerics, but I think some of our current usages, like "2^bits" https://developer.mozilla.org/en-US/docs/web/javascript/reference/global_objects/bigint/asuintn#returns, might not be supported (?).

[hamishwillee]

I have also seen ^ used as a superscript operator in a flavour of markdown. This is a case where I'd be happy with either or both of your options - because as you say the occurrence is low.

[Gregoor]

Oh wow, I thought unicode superscript was a thing for latin characters but it turns out there is only a cursed version of the alphabet, e.g. 2ᵇⁱᵗˢ
Well, at least we won't have tools in english then, that localizers wouldn't be able to use.

[wbamberg]

Yeah, for authoring I agree that either of these choices is OK. From a conversion point of view, it would probably be best to leave them as HTML.

[wbamberg]

I have also seen ^ used as a superscript operator in a flavour of markdown.

In fact since Yari, <sup> doesn't work in code, as reported in https://github.com/mdn/content/pull/858 , and using ^ was suggested as an alternative there. But I'm happier with that in code comments than in general prose.

[sideshowbarker]

Grepping in the JavaScript docs reports <sup> in 99 lines, of which 63 are using it for indicating exponentiation.

For those cases, I think we could eliminate the need to use superscript at all by adopting a practice of instead using the JavaScript ** exponentiation operator for those cases. That is, 2**53 rather than 2<sup>53</sup>.

Using the JavaScript ** exponentiation operator for all those cases has the advantage that it works if you paste it as-is into code or into the devtools console or Node.js REPL.

I agree 2**53 is not aesthetically super-pretty and for writing about exponentiation in normal (non-HTML) text, I personally like using 2^53 with a caret way better.

But since the JavaScript docs are for JavaScript developers, when they see it in MDN docs they’re either already going to be familiar with it and instantly recognize it for what it is — or else for less-experienced developers, they’re going to actually learn from seeing it that 2**53 is how exponentiation is done in JavaScript.

Another 35 cases are for 1<sup>st</sup>, 2<sup>nd</sup>, 3<sup>rd</sup>, 4<sup>th</sup>, etc. — which could be replaced by writing them out as first, second, third, fourth, etc., or else 1st, 2nd, 3rd, 4th, etc.

So those could be considered cases where using superscript was kind of superfluous to begin with.

The one other case in the JavaScript docs is <strong>JavaScript</strong><sup>®</sup>. That also seems superfluous and could be dealt with by not using superscript there, or else by not having a registered trademark sign there at all to begin with.

So for the JavaScript docs, it seem we could say that we could deal with superscript when moving them to markdown is to just make them not have any superscript — by instead using the ** exponentiation operator, or writing words out without it.

[sideshowbarker]

Grepping across the docs as a whole, I count 444 lines with <sup>, and of those, 196 are for exponentiation.

345 of the total <sup> lines are in docs outside the JavaScript tree, and of those 133 are for exponentiation.

From looking through those cases, I think they all could be unambiguously replaced with a ^ caret.

I think in the context of the goals we’re trying achieve by moving to markdown, it’s absolutely better to use the ^ caret for those cases than using a <sup> carve-out.

As far as the remaining 208 lines with <sup> outside the JavaScript tree, a least 197 of those appear to be for marking up footnote references; for example, <sup><a href="#g722-foot-1">[1]</a>. So those don’t seem like cases where the superscript is essential — arguably, not having them in superscript is better for usability (smaller numbers are harder to click).

The remaining dozen or so cases are either for 1<sup>st</sup>, 2<sup>nd</sup>, 3<sup>rd</sup>, 4<sup>th</sup> or for Java<sup>TM</sup>, Microsoft<sup>®</sup>, <a href="https://www.w3.org/">W3C</a><sup>®</sup> and such — with one exception: The instances of <sup> in the files/en-us/web/html/element/sup/index.html document itself.

So the bottom line is that the 444 lines with <sup> in the entire tree, the only place we’re currently using <sup> that’s really necessary is in the files/en-us/web/html/element/sup/index.html document itself — where we want to show how <sup> gets rendered; for example, in French, the word "mademoiselle" can be abbreviated "M<sup>lle</sup>".

[Ryuno-Ki]

Regarding the footnotes, I think, there is an extension to render endnotes, which could be adopted.
I agree with not putting them in <sup> for the stated reason.

[hamishwillee]

@sideshowbarker Good analysis above.

• I think we're better off being consistent and using ^ everywhere than doing something different for JavaScript (**).
• Not a fan of footnotes in Web docs. They could be dealt with differently.

My vote is that we strongly encourage use of ^ and first, second, whatever, but we still support <sup>.

Is there an equivalent for <sub>? I see 409 hits in 26 files. Many of which appear pre blocks to describe matrix elements.

[Ryuno-Ki]

In ASCIImath you would use _ for <sub>: http://asciimath.org/

[hamishwillee]

In ASCIImath you would use _ for _{: http://asciimath.org/}

Unfortunately that's italic in markdown. I suspect we could use mathjax or similar to do sub in equations.

[Ryuno-Ki]

Escape it?

[Ryuno-Ki]

Oh, and MathJax can use ASCIImath, too :-)

[sideshowbarker]

Escape it?

At that point, seems like it’s getting ugly enough that it’s time to give up and just use <sub></sub>.

Regardless, I think unlike the ^ caret notation for indicating exponentiation — which I think we can expect many MDN authors/contributors to likely be familiar with — I wouldn’t expect nearly as many MDN authors/contributors to be familiar with the _ underscore notation for subscript.

So for the subscript case, I have kinda have to concede that going with <sub><sub> HTML markup seems the best option.

[wbamberg]

My vote is that we strongly encourage use of ^ and first, second, whatever, but we still support \^.

I like this, and have opened https://github.com/mdn/content/pull/4804 to say it.

[wbamberg]

Closing this, as we have a resolution in https://github.com/mdn/content/pull/4804 and the converter behaviour is pretty clear.

I filed https://github.com/mdn/content/issues/5012 to track removing usages of these elements where we can.