Remove `sup` from javascript docs #5128

wbamberg · 2021-05-19T19:41:31Z

As discussed in #4578 and in particular #4578 (comment), I've gone through the JS docs, replacing <sup> with caret, or the ordinal word like "first", and in one case removing it entirely.

One case that needed care is 2<sup>63</sup>-1, which renders like:

2⁶³-1

...but gives the less readable (to my eye)

2^63-1

...when converted. Many of these already used spaces:

2⁶³ - 1

...but I've tried to make sure that they all do, so we get:

2^63 - 1

...which looks better to me.

github-actions · 2021-05-19T19:43:46Z

Preview URLs

Flaws

Note! 30 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters
Title: Rest parameters
on GitHub
Flaw count: 2

broken_links:
- Can't resolve https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
- Is currently http:// but can become https://

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
Title: Number
on GitHub
Flaw count: 1

macros:
- /en-US/docs/Web/JavaScript/Reference/Arithmetic%20operators does not exist

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger
Title: Number.isSafeInteger()
on GitHub
Flaw count: 1

broken_links:
- Is currently http:// but can become https://

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
Title: TypedArray
on GitHub
Flaw count: 1

macros:
- /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype redirects to /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Array
Title: Array() constructor
on GitHub
Flaw count: 1

broken_links:
- Anchor not lowercase

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from
Title: Array.from()
on GitHub
Flaw count: 1

broken_links:
- Can't resolve /en-US/docs/Web/JavaScript/Guide/iterable

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
Title: Array.prototype.forEach()
on GitHub
Flaw count: 2

broken_links:
- Anchor not lowercase
- No need for the pathname in anchor links if it's the same page

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt
Title: parseInt()
on GitHub
Flaw count: 1

broken_links:
- Anchor not lowercase

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind
Title: Function.prototype.bind()
on GitHub
Flaw count: 1

macros:
- /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/prototype does not exist

URL: /en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_NOT
Title: Bitwise NOT (~)
on GitHub
Flaw count: 2

broken_links:
- Anchor not lowercase
bad_pre_tags:
- <pre><code>CODE can be just <pre>CODE

URL: /en-US/docs/Web/JavaScript/Data_structures
Title: JavaScript data types and data structures
on GitHub
Flaw count: 1

broken_links:
- Can't resolve /en-US/docs/Storage

URL: /en-US/docs/Web/JavaScript/Typed_arrays
Title: JavaScript typed arrays
on GitHub
Flaw count: 2

broken_links:
- Can't resolve /en-US/docs/Code_snippets/StringView
- Is currently http:// but can become https://

URL: /en-US/docs/Web/JavaScript/Language_Resources
Title: JavaScript language resources
on GitHub
Flaw count: 8

broken_links:
- Is currently http:// but can become https://
- Is currently http:// but can become https://
- Can't resolve /en-US/docs/JavaScript/ECMAScript_5_support_in_Mozilla
- Can't resolve /en-US/docs/E4X
- Is currently http:// but can become https://
- and 3 more flaws omitted

URL: /en-US/docs/Web/JavaScript/About_JavaScript
Title: About JavaScript
on GitHub
Flaw count: 5

broken_links:
- Can't resolve /en-US/docs/Rhino
- Is currently http:// but can become https://
- Is currently http:// but can become https://
- Is currently http:// but can become https://
- Can't resolve /en-US/docs/Rhino

External URLs

URL: /en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript
Title: A re-introduction to JavaScript (JS tutorial)
on GitHub

https://en.wikipedia.org/wiki/Double_precision_floating-point_format (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Functions/rest_parameters
Title: Rest parameters
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Errors/Resulting_string_too_large
Title: RangeError: repeat count must be less than infinity
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
Title: Number
on GitHub

https://en.wikipedia.org/wiki/Floating-point_arithmetic (2 times) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger
Title: Number.isSafeInteger()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
Title: Number.MIN_SAFE_INTEGER
on GitHub

https://en.wikipedia.org/wiki/Double_precision_floating-point_format (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/IEEE_floating_point (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_VALUE
Title: Number.MIN_VALUE
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/EPSILON
Title: Number.EPSILON
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_VALUE
Title: Number.MAX_VALUE
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
Title: Number.MAX_SAFE_INTEGER
on GitHub

https://en.wikipedia.org/wiki/Double_precision_floating-point_format (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/IEEE_floating_point (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math
Title: Math
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/exp
Title: Math.exp()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow
Title: Math.pow()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/expm1
Title: Math.expm1()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/hypot
Title: Math.hypot()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random
Title: Math.random()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
Title: TypedArray
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every
Title: Array.prototype.every()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Array
Title: Array() constructor
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from
Title: Array.from()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice
Title: Array.prototype.splice()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
Title: Array.prototype.forEach()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some
Title: Array.prototype.some()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length
Title: Array.prototype.length
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/fromCharCode
Title: String.fromCharCode()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt
Title: parseInt()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/bind
Title: Function.prototype.bind()
on GitHub

No external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply
Title: Function.prototype.apply()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse
Title: Date.parse()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/UTC
Title: Date.UTC()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now
Title: Date.now()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt
Title: BigInt
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/asUintN
Title: BigInt.asUintN()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/asIntN
Title: BigInt.asIntN()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
Title: Object.prototype.toString()
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Reference/Operators/Bitwise_NOT
Title: Bitwise NOT (~)
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Data_structures
Title: JavaScript data types and data structures
on GitHub

https://en.wikipedia.org/wiki/Double_precision_floating-point_format (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Typed_arrays
Title: JavaScript typed arrays
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Language_Resources
Title: JavaScript language resources
on GitHub

https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=55755 (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators
Title: Expressions and operators
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling
Title: Control flow and error handling
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Guide/Indexed_collections
Title: Indexed collections
on GitHub

No new external URLs

URL: /en-US/docs/Web/JavaScript/Guide/Numbers_and_dates
Title: Numbers and dates
on GitHub

https://en.wikipedia.org/wiki/Double-precision_floating-point_format (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/JavaScript/About_JavaScript
Title: About JavaScript
on GitHub

https://en.wikipedia.org/wiki/First-class_function (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/JavaScript (1 time) (Note! This may be a new URL 👀)
https://en.wikipedia.org/wiki/Prototype-based_programming (1 time) (Note! This may be a new URL 👀)

(this comment was updated 2021-05-21 05:29:55.409297)

hamishwillee · 2021-05-21T01:53:02Z

files/en-us/web/javascript/about_javascript/index.html

@@ -11,7 +11,7 @@

 <h2 id="What_is_JavaScript">What is JavaScript?</h2>

-<p><strong>JavaScript</strong><sup>®</sup> (often shortened to <strong>JS</strong>) is a lightweight, interpreted, object-oriented language with <a href="https://en.wikipedia.org/wiki/First-class_function">first-class functions</a>, and is best known as the scripting language for Web pages, but it's <a href="https://en.wikipedia.org/wiki/JavaScript#Uses_outside_Web_pages">used in many non-browser environments</a> as well. It is a <a class="mw-redirect" href="https://en.wikipedia.org/wiki/Prototype-based_programming" title="Prototype-based">prototype-based</a>, multi-paradigm scripting language that is dynamic, and supports object-oriented, imperative, and functional programming styles.</p>
+<p><strong>JavaScript</strong> (often shortened to <strong>JS</strong>) is a lightweight, interpreted, object-oriented language with <a href="https://en.wikipedia.org/wiki/First-class_function">first-class functions</a>, and is best known as the scripting language for Web pages, but it's <a href="https://en.wikipedia.org/wiki/JavaScript#Uses_outside_Web_pages">used in many non-browser environments</a> as well. It is a <a class="mw-redirect" href="https://en.wikipedia.org/wiki/Prototype-based_programming" title="Prototype-based">prototype-based</a>, multi-paradigm scripting language that is dynamic, and supports object-oriented, imperative, and functional programming styles.</p>


I am assuming that since I've not seen it before on MDN we don't generally markup the use of trademarks, copyrights etc. If so, good.

hamishwillee · 2021-05-21T01:56:17Z

files/en-us/web/javascript/data_structures/index.html

@@ -377,31 +377,31 @@ <h3 id="Indexed_collections_Arrays_and_typed_Arrays">Indexed collections: Arrays
  </tr>
  <tr>
   <td>{{jsxref("Float32Array")}}</td>
-   <td><code>1.2</code>×<code>10<sup>-38</sup></code> to <code>3.4</code>×<code>10<sup>38</sup></code></td>
+   <td><code>1.2</code>×<code>10^-38</code> to <code>3.4</code>×<code>10^38</code></td>


It might be better for base 10 exponentials to represent using E, as this is well understood (even by me): E.g.1.2×10^-38 to 1.2E-38

hamishwillee · 2021-05-21T01:56:50Z

files/en-us/web/javascript/data_structures/index.html

   <td>4</td>
   <td>32-bit IEEE floating point number (7 significant digits e.g., <code>1.1234567</code>)</td>
   <td><code>unrestricted float</code></td>
   <td><code>float</code></td>
  </tr>
  <tr>
   <td>{{jsxref("Float64Array")}}</td>
-   <td><code>5.0</code>×<code>10<sup>-324</sup></code> to <code>1.8</code>×<code>10<sup>308</sup></code></td>
+   <td><code>5.0</code>×<code>10^-324</code> to <code>1.8</code>×<code>10^308</code></td>


Use E? https://github.com/mdn/content/pull/5128/files#r636583402

I won't mark up any more of these.

hamishwillee · 2021-05-21T01:59:11Z

files/en-us/web/javascript/language_resources/index.html

@@ -23,23 +23,23 @@
   <th colspan="4">Current editions</th>
  </tr>
   <tr>
-   <td>ECMA-262 11<sup>th</sup> Edition</td>
+   <td>ECMA-262 eleventh Edition</td>


I don't know why, but it feels like eleventh should be capitalised or edition should not be. My preference: "ECMA-262 (eleventh edition)"

Actually my preference is: ECMA-262 11th Edition.
I don't care that the sub is missing, it just looks better.

hamishwillee · 2021-05-21T01:59:46Z

files/en-us/web/javascript/language_resources/index.html

   <td>
    <p><a href="https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-262.pdf">PDF</a>, <a href="https://ecma-international.org/ecma-262/11.0/index.html">HTML</a>, <a href="https://tc39.github.io/ecma262/">Working draft</a>, <a href="https://github.com/tc39/ecma262">repository</a></p>
   </td>
   <td>2020</td>
   <td>ECMAScript 2020 Language Specification</td>
  </tr>
  <tr>
-   <td>ECMA-262 10<sup>th</sup> Edition</td>
+   <td>ECMA-262 tenth Edition</td>


As for https://github.com/mdn/content/pull/5128/files#r636584266 - just looks wrong to have the case go up and down. Ignore if you want.

hamishwillee · 2021-05-21T02:01:22Z

files/en-us/web/javascript/reference/global_objects/array/length/index.html


-<pre class="brush: js">var namelistA = new Array(4294967296); //2 to the 32nd power<sup> = </sup>4294967296
+<pre class="brush: js">var namelistA = new Array(4294967296); //2 to the 32nd power = 4294967296


I just want to point out that we're happy to have "32nd" here. I think using first is better, but I would not be offended by 1st, 2nd, etc.

hamishwillee · 2021-05-21T02:03:16Z

files/en-us/web/javascript/reference/global_objects/bigint/asuintn/index.html

@@ -33,7 +33,7 @@ <h3 id="Parameters">Parameters</h3>
 <h3 id="Returns">Returns</h3>

 <p>The value of <code><var>bigint</var></code> modulo
-  2<sup><code><var>bits</var></code></sup>, as an unsigned integer.</p>
+  2^<code><var>bits</var></code>, as an unsigned integer.</p>


Fix is OK, but would have killed the <var> markup too.

This will go in the Markdown conversion (there are a billion on them).

hamishwillee · 2021-05-21T02:05:55Z

files/en-us/web/javascript/reference/global_objects/math/index.html

@@ -75,7 +75,7 @@ <h2 id="Static_methods">Static methods</h2>
 <dt>{{jsxref("Global_Objects/Math/cosh", "Math.cosh(<var>x</var>)")}}</dt>
 <dd>Returns the hyperbolic cosine of <code><var>x</var></code>.</dd>
 <dt>{{jsxref("Global_Objects/Math/exp", "Math.exp(<var>x</var>)")}}</dt>
- <dd>Returns <code>E<var><sup>x</sup></var></code>, where <code><var>x</var></code> is the argument, and <code>E</code> is Euler's constant (<code>2.718</code>…, the base of the natural logarithm).</dd>
+ <dd>Returns <code>E<var>^x</var></code>, where <code><var>x</var></code> is the argument, and <code>E</code> is Euler's constant (<code>2.718</code>…, the base of the natural logarithm).</dd>


e not E is symbol for Euler's constant. It wouldn't matter, except that using E for base10 exponential is desirable IMO.

PS My be mentioned in a few other cases too.

hamishwillee

Nice job.

Summarizing the other comments, IMO OK as is, but slightly better if:

Use E for base 10 exponentials - e.g. 1.2E56.
Use 1st, 2nd, etc when referring to JavaScript editions.

wbamberg · 2021-05-21T04:48:42Z

Thanks for the review @hamishwillee ! I agree about the "1st" thing, and I've updated to use E notation as well, though
I'm pretty much neutral on that. I am a bit mathematically challenged though.

hamishwillee

Well, looks good to me. I've approved so you can self merge if you like, or wait for @sideshowbarker to also have a go.

sideshowbarker

Beautiful

files/en-us/web/javascript/guide/control_flow_and_error_handling/index.html

…ng/index.html

files/en-us/web/javascript/reference/errors/resulting_string_too_large/index.html

files/en-us/web/javascript/reference/global_objects/array/array/index.html

wbamberg · 2021-05-21T06:20:56Z

Thanks both for your sharp eyes!

wbamberg added 2 commits May 19, 2021 12:27

Remove sup element from JS docs

c957dcb

Add spaces in some replacements

8d25560

wbamberg requested a review from a team as a code owner May 19, 2021 19:41

wbamberg requested review from sideshowbarker and removed request for a team May 19, 2021 19:41

wbamberg changed the title ~~Remove sup javascript~~ Remove sup from javascript docs May 19, 2021

hamishwillee self-requested a review May 21, 2021 01:49

hamishwillee reviewed May 21, 2021

View reviewed changes

hamishwillee approved these changes May 21, 2021

View reviewed changes

wbamberg added 3 commits May 20, 2021 21:04

Use numbers not words for ordinals

5bfd648

Use a little e

13ef740

Use E notation, and fix a few more stray ordinals

c57a8cd

hamishwillee approved these changes May 21, 2021

View reviewed changes

sideshowbarker approved these changes May 21, 2021

View reviewed changes

sideshowbarker reviewed May 21, 2021

View reviewed changes

files/en-us/web/javascript/guide/control_flow_and_error_handling/index.html Outdated Show resolved Hide resolved

Update files/en-us/web/javascript/guide/control_flow_and_error_handli…

a7712b3

…ng/index.html

sideshowbarker approved these changes May 21, 2021

View reviewed changes

files/en-us/web/javascript/reference/errors/resulting_string_too_large/index.html Outdated Show resolved Hide resolved

files/en-us/web/javascript/reference/global_objects/array/array/index.html Outdated Show resolved Hide resolved

Apply suggestions from code review

edd4b02

wbamberg merged commit ad09d9d into mdn:main May 21, 2021

wbamberg mentioned this pull request Jun 10, 2021

[Markdown] Preparing CSS docs for Markdowning #5865

Closed

13 tasks

wbamberg mentioned this pull request Jul 26, 2021

[Markdown] [CSS] Handle sup and sub in the CSS docs #7267

Closed

github-actions bot locked as resolved and limited conversation to collaborators Aug 11, 2022

wbamberg deleted the remove-sup-javascript branch October 15, 2022 17:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove `sup` from javascript docs #5128

Remove `sup` from javascript docs #5128

wbamberg commented May 19, 2021

github-actions bot commented May 19, 2021 •

edited

Loading

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

wbamberg May 21, 2021

hamishwillee May 21, 2021

hamishwillee May 21, 2021

hamishwillee left a comment

wbamberg commented May 21, 2021

hamishwillee left a comment

sideshowbarker left a comment

wbamberg commented May 21, 2021


		<pre class="brush: js">var namelistA = new Array(4294967296); //2 to the 32nd power<sup> = </sup>4294967296
		<pre class="brush: js">var namelistA = new Array(4294967296); //2 to the 32nd power = 4294967296

Remove sup from javascript docs #5128

Remove sup from javascript docs #5128

Conversation

wbamberg commented May 19, 2021

github-actions bot commented May 19, 2021 • edited Loading

Preview URLs

Flaws

External URLs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee left a comment

Choose a reason for hiding this comment

wbamberg commented May 21, 2021

hamishwillee left a comment

Choose a reason for hiding this comment

sideshowbarker left a comment

Choose a reason for hiding this comment

wbamberg commented May 21, 2021

Remove `sup` from javascript docs #5128

Remove `sup` from javascript docs #5128

github-actions bot commented May 19, 2021 •

edited

Loading