search

mdn / yari

The platform code behind MDN Web Docs
Mozilla Public License 2.0
1.17k stars 488 forks source link

Triage all KumaScript macros that are called from our JS docs #2846

Closed wbamberg closed 4 weeks ago

wbamberg commented 4 years ago

Depends on https://github.com/mdn/sprints/issues/2519

  1. Run our linter on all the JS docs to get a list of all the KumaScript macros that they call.
  2. Go through all the macros, and decide for each one whether we should:
    • render: replace the macro call with the static HTML that it generates
    • remove: remove the macro call
    • replace: design and implement a replacement for the KumaScript macro

These decisions should be made public and reviewed by our content lead.

Acceptance criteria

We have a resolution (render, remove, replace) for every macro called from the JS docs.

Elchi3 commented 4 years ago

This list of macros uses https://github.com/mdn/stumptown-content/pull/264 to lint for all macro calls under /en-US/docs/Web/JavaScript:

Macro name                         number of calls
--------------------------------------------------
jsxref                             7387
Spec2                              1839
SpecName                           1832
EmbedInteractiveExample            490
jsSidebar                          241
page                               142
Glossary                           142
domxref                            89
bug                                84
js_property_attributes             82
htmlelement                        50
PreviousNext                       32
anch                               30
geckoRelease                       21
Obsolete_Header                    10
EmbedLiveSample                    9
EmbedTest262ReportResultsTable     8
interwiki                          5
htmlattrxref                       4
obsolete_inline                    4
JSFiddleEmbed                      4
jsindex                            2
HTTPHeader                         2
Previous                           2
JSRef                              1
SectionOnPage                      1
compat                             1
Note                               1
Gecko                              1
RFC                                1
ListSubPages                       1
Next                               1
Index                              1
wbamberg commented 4 years ago

This comment presents an initial triage for the 33 macros listed above and called from our JS docs.

It should assign to each macro one of the following three options:

For macros we intend to replace, there's going to be a further choice about whether we expose them to guide pages via "directives" (as we already do for BCD, for example), or restrict them to pages that are of a particular recipe (as we do for specifications, for example).

* jsSidebar

* JSRef

Replace

We're intending to replace sidebars, of course.

* jsxref

* domxref

* bug

* HTMLElement

* anch

* interwiki

* htmlattrxref

* HTTPHeader

* SectionOnPage

* RFC

* Glossary

Render

These are all XRef macros, that convert some arguments (a partial path, in effect, plus sometimes some extra arguments) to a link.

* PreviousNext

* Previous

* Next

Replace

These are used to add specially styled "Next" and "Previous" links to documents that are part of a linear sequence. We don't yet have an implementation of this in stumptown, but see https://github.com/mdn/stumptown-content/issues/265 for a proposal.

* js_property_attributes

Replace

This is an "info box" for JS properties. See e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length.

We know we will want info box support in stumptown (see also https://github.com/mdn/stumptown-content/issues/106). The actual items in this case seem simple to support (just booleans).

These macros are specific to certain structured page types, so I don't think we should expose them to guide pages as "directives".

* obsolete_inline

* Obsolete_Header

* Note

Remove

These are all "badge/banner" macros. Banners add specially styled blocks of text, while badges add specially styled inline text.

See for example: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators#Non-standard_features and https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Array_comprehensions for examples of the "obsolete_*" macros.

For "Note", see for example the first paragraph under https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split#Using_split.

I propose removing all three of these. I expect removing Note might be controversial. Personally I think we should prefer to avoid these kinds of note/warning boxes and let the text speak for itself. If we did want to support them I'm not sure what would be the best way. Perhaps we could abuse Markdown code fences?

* SpecName

* Spec2

Replace

These are used to build spec tables.

They are already supported. We don't need to expose them to guide pages as directives.

* EmbedInteractiveExample

Replace

Already supported. We don't need to expose them to guide pages as directives.

* EmbedTest262ReportResultsTable

Replace

Embeds a test report table in an iframe. See for example https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis#Implementation_progress.

If we want to keep this feature, we'll need to replace this macro. We don't need to expose them to guide pages as directives.

* EmbedLiveSample

Replace

We already support this, and it's enabled for guide pages.

* Compat

Replace

We already support this, and it's enabled for guide pages.

* page

Render

This page is used to include content from one page in another page.

I would like us to render out this macro, in general. I think ad hoc transcluding of content is a kind of content antipattern (mostly because the original source of the doc doesn't know where it is included, so it's easy to edit it so it doesn't make sense in the transcluding context). But it is used quite extensively in the JS docs to include instance properties and methods from the corresponding Foo/prototype page.

For example, https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray uses it to include instance properties from https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype.

I think we should consider whether the JS docs really want to be doing this. If they do, we should find a way to support it.

* geckoRelease

Remove

This is used in pages like WeakMap.set(), where source like:

Prior to Firefox 33 {{geckoRelease("33")}}, WeakMap.prototype.set returned undefined and was not chainable. This has been fixed ({{bug(1031632)}}). The behavior could be found in Chrome/v8 as well (issue).

gives output like:

Prior to Firefox 33 (Firefox 33 / Thunderbird 33 / SeaMonkey 2.30), WeakMap.prototype.set returned undefined and was not chainable. This has been fixed (bug 1031632). The behavior could be found in Chrome/v8 as well (issue).

So the macro converts "33" -> "(Firefox 33 / Thunderbird 33 / SeaMonkey 2.30)". Really, that paragraph should be removed, and its contents represented in BCD if it's important. But that's a manual update. For the sake of the machines, it would be fine to just remove the macro call, and the output would be:

Prior to Firefox 33, WeakMap.prototype.set returned undefined and was not chainable. This has been fixed (bug 1031632). The behavior could be found in Chrome/v8 as well (issue).

* JSFiddleEmbed

Replace, after changing to use EmbedLiveSample

Embeds a JSFiddle in the page.

These are only used in one page, https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Closures. Using JSFiddle embeds doesn't add any advantages over a normal live sample, as far as I can tell.

* jsindex

Replace

These are used to build two landing pages: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Properties_Index https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Methods_Index

I'd suggest we rework these pages to be "stumptown landing page compatible", and scrape them as landing pages. We can I hope use stumptown "link lists" to replace the actual macro calls here.

* Gecko

Remove

Used in one page: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/search. 

* ListSubPages

Replace

Used in one page: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors, which looks like it wants to be a landing page. I'd suggest we rework this page to be "stumptown landing page compatible", and scrape it as as a landing page. Listing subpages is already supported in stumptown "link lists".

* Index

Replace ??

Used in only one page, https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Index. I think these pages are used for DocStatus, and I assume that in GitHub that whole system will be replaced. However we haven't yet thought about what the requirements are for this or how we will do it.

Summary

So to summarise, I'd say:

Remove:

Render:

Replace:

[1] already supported in stumptown

ddbeck commented 4 years ago

This is great. Thank you for writing all of these up, Will.

There was only one macro decision that I had misgivings about and that was replacing EmbedTest262ReportResultsTable. Can we remove this one instead? It seems to cover a lot of the same ground as BCD but lacks details to make it actionable (e.g., so what if V8 passes the tests? does Chrome actually ship that version of V8? I don't know and the report doesn't tell me).

I take it we'll have separate issues to hash out the implementation details of removing or rendering out specific macros? For example, I'd like to see the potential diff of removing geckoRelease to make sure it's not being used all alone, or I'd like to suggest annotating the source for the HTML that removes macros. I haven't gotten into the weeds on this here because I figure it can wait, but please correct me if I'm wrong.

wbamberg commented 4 years ago

This is great. Thank you for writing all of these up, Will.

There was only one macro decision that I had misgivings about and that was replacing EmbedTest262ReportResultsTable. Can we remove this one instead? It seems to cover a lot of the same ground as BCD but lacks details to make it actionable (e.g., so what if V8 passes the tests? does Chrome actually ship that version of V8? I don't know and the report doesn't tell me).

I'd be happy to remove it, but it is very new (https://github.com/mdn/kumascript/pull/1245). As I understand it, it is experimental and I don't know what the status of the experiment is. I think Florian's input is needed here.

I take it we'll have separate issues to hash out the implementation details of removing or rendering out specific macros? For example, I'd like to see the potential diff of removing geckoRelease to make sure it's not being used all alone, or I'd like to suggest annotating the source for the HTML that removes macros. I haven't gotten into the weeds on this here because I figure it can wait, but please correct me if I'm wrong.

Well, some of this work has to be done now, just to make a sensible determination. I mean, we need to have some idea of what they do and where/how they are used, and I've done some of that digging in the comment above. And I do want to be careful in this step and get to quite a high degree of confidence that we are making good decisions. But yes, there are issues for the next steps (e.g. https://github.com/mdn/sprints/issues/2524) and I don't expect us to get all the decisions right at this point. Does that answer your concern?

chrisdavidmills commented 4 years ago

Great work here @wbamberg !

I agree with most of it, and just had the odd few comments/queries:

wbamberg commented 4 years ago

Thanks Chris, for taking a look!

Could we add something to the renderer so that whenever it finds a paragraph with "Note: " or "Warning: " at the start of it, it just adds a note or warning class to the paragraph element in the final rendered version? So it just infers it from the text rather than needing a macro?

Some difficulties with this:

One reason for suggesting we abuse code fencing is that you get something like preview support, so source like this:

blah blah blah

```note
This is a note we've decided to highlight for some reason.

We can have 2 paragraphs.

[Other Markup doesn't work, though](https://example.com), which is sad
```

some more stuff that isn't in the note.

is shown in my editor's preview like this:

Screen Shot 2019-12-21 at 12 00 09 PM

I think in most cases, removing notes from MDN pages improves them. What happens is that people have A Thing they want to say, and it's important to them, because they're motivated enough to add it, so they mark it up to show how important it is. But when everyone does that, it's the documentation equivalent of a party where everyone's talking at once, so some people start talking louder to be heard, then eventually everyone's shouting and you can't hear anything.

For example, see the section of the JS docs that use {{Note}}:

Screen Shot 2019-12-21 at 11 45 16 AM

I think this passage would be improved by just removing the Note styling.

"I think these pages are used for DocStatus" - are we still using the DocStatus pages for anything? I've never really used them, and I think they were mainly used as community hubs for volunteers trying to find things to do? I reckon we can probably meet this need in a cleverer way in the new world, using the available GitHub machinery

I think they are used only by localizers, and @SphinxKnight has told me that they are useful and used. And yes, I expect this would have an out-of-content solution in stumptown, but that doesn't absolve us from thinking about it :).

chrisdavidmills commented 4 years ago

Some difficulties with this / abusing code fencing

Valid points here, thanks for taking the time to explain the difficulties in so much detail. It is taking me a while to get into the stumptown mindset when thinking about how things will work, and this is very helpful! So yes, the code fencing thing does look it could work.

I totally agree with you on note usage too; as you said before, the content should largely just speak for itself.

ddbeck commented 4 years ago

Well, some of this work has to be done now, just to make a sensible determination. I mean, we need to have some idea of what they do and where/how they are used, and I've done some of that digging in the comment above. And I do want to be careful in this step and get to quite a high degree of confidence that we are making good decisions. But yes, there are issues for the next steps (e.g. mdn/yari#2844) and I don't expect us to get all the decisions right at this point. Does that answer your concern?

OK, that's fine. If you're pretty confident that the macros can be removed safely now, then that's good enough for me. Also, I mis-wrote before: my hope was that for macros that get rendered out to have an annotation as such (e.g., a data- attribute to note that the HTML used to be a macro); this is the sort of detail that I assumed would have to get written up in a user story for the dev team to implement.

escattone commented 4 years ago

This is really exciting progress and looks great to me, thanks @wbamberg, @Elchi3, @ddbeck, and @chrisdavidmills!!

I had one thought/question while reading through the macro decisions. I was wondering if it might make more sense to remove the page macro rather than render it? In the example provided (https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), the TypedArray prototype section of that page would have a link to https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype (generated by rendering-out the jsxref("TypedArray.prototype") macro call), so duplicating the Properties and Methods sections from that linked page, via the page('en-US/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype','Properties') and page('en-US/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype','Methods') macro calls, seems like it violates the DRY principle for no compelling reason, since the user could get to that information by following the link? This argument to remove rather than render assumes that the page macro calls are always immediately preceded by jsxref macro calls, which may not be the case though.

wbamberg commented 4 years ago

That's a very interesting comment @escattone ! In this case I agree with you, remove is better. But as you imply, page is a very general-purpose macro, and removing it here is only an option in this particular context.

If we had a tool that let us say: "remove {{page}} only for pages under /en-US/docs/Web/JavaScript", and we could be fairly sure it's only called in this context (which means we have to spend the time checking through all 142 calls to this macro), then I'd be happy to do this for JS.

So this also suggests we could triage macros differently in different sections of the docs.

escattone commented 4 years ago

@wbamberg I did some analysis of all of the documents under /en-US/docs/Web/JavaScript. Out of 1052 total documents descendant from /en-US/docs/Web/JavaScript, only 53 documents contain calls to the page macro. The following are the macro calls, in the order in which they are made, within each of those 53 documents. Scanning down the list, I marked the documents where one or more page macro calls might be able to be removed rather than rendered, and it seemed to me that 31 documents met that criteria (they're preceded with **DOC: rather than DOC: in the data below). Within those 31 documents, I found 60 page macro calls (out of the 139 total page macro calls within all 53 documents -- so less than 50%) which I thought could be removed rather than rendered (they're marked with **page rather than page). After looking at this data, I think your original decision to render is right on. Trying to determine when removal might be better doesn't seem worth it.

DOC: /en-US/docs/Web/JavaScript/Typed_arrays (JavaScript typed arrays)
   JsSidebar("Advanced")
   jsxref("Array")
   jsxref("ArrayBuffer")
   jsxref("ArrayBuffer")
   jsxref("DataView")
   page("/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", "TypedArray_objects")
   jsxref("DataView")
   Glossary("Endianness")
   jsxref("ArrayBuffer")
   jsxref("Uint8ClampedArray")
   jsxref("Array")
   jsxref("Array.from")
   SpecName('Typed Array')
   Spec2('Typed Array')
   SpecName('ES2015', '#sec-typedarray-objects', 'TypedArray Objects')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-typedarray-objects', 'TypedArray Objects')
   Spec2('ESDraft')
   Compat("javascript.builtins.Int8Array")
   Glossary("Endianness")
DOC: /en-US/docs/Web/JavaScript/Data_structures (JavaScript data types and data structures)
   jsSidebar("More")
   Glossary("Primitive", "primitives")
   Glossary("Boolean")
   Glossary("Null")
   Glossary("Undefined")
   Glossary("Number")
   Glossary("BigInt")
   Glossary("String")
   Glossary("Symbol")
   Glossary("Object")
   Glossary("Boolean")
   jsxref("Boolean")
   jsxref("null")
   Glossary("Null")
   jsxref("undefined")
   Glossary("Undefined")
   jsxref("NaN")
   jsxref("Infinity", "+/-Infinity")
   jsxref("Number.MAX_VALUE")
   jsxref("Number.MIN_VALUE")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("Number.MIN_SAFE_INTEGER")
   jsxref("BigInt")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("TypeError")
   jsxref("String")
   domxref("XMLHttpRequest")
   Glossary("Symbol")
   jsxref("Symbol")
   Glossary("Identifier", "identifier")
   jsxref("Symbol")
   page("/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", "TypedArray_objects", "", 0, 3)
   jsxref("Set")
   jsxref("WeakSet")
   jsxref("Map")
   jsxref("WeakMap")
   Glossary("JSON")
   jsxref("JSON")
   SpecName('ES1')
   Spec2('ES1')
   SpecName('ES5.1', '#sec-8', 'Types')
   Spec2('ES5.1')
   SpecName('ES2015', '#sec-ecmascript-data-types-and-values', 'ECMAScript Data Types and Values')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-ecmascript-data-types-and-values', 'ECMAScript Data Types and Values')
   Spec2('ESDraft')
DOC: /en-US/docs/Web/JavaScript/Reference (JavaScript reference)
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects', 'Standard_objects_by_category')
   page('/en-US/docs/Web/JavaScript/Reference/Statements', 'Statements_and_declarations_by_category')
   page('/en-US/docs/Web/JavaScript/Reference/Operators', 'Expressions_and_operators_by_category')
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Function (Function)
   jsxref("eval")
   EmbedInteractiveExample("pages/js/function-constructor.html")
   jsxref("Function.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/prototype', 'Methods')
   jsxref("Function.prototype")
   jsxref("eval")
   SpecName('ES1')
   Spec2('ES1')
   SpecName('ES5.1', '#sec-15.3', 'Function')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-function-objects', 'Function')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-function-objects', 'Function')
   Spec2('ESDraft')
   Compat("javascript.builtins.Function")
   jsxref("Functions", "Functions and function scope")
   jsxref("Statements/function", "function statement")
   jsxref("Operators/function", "function expression")
   jsxref("Statements/function*", "function* statement")
   jsxref("Operators/function*", "function* expression")
   jsxref("AsyncFunction")
   jsxref("GeneratorFunction")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView (DataView)
   jsxref("ArrayBuffer")
   EmbedInteractiveExample("pages/js/dataview-constructor.html")
   jsxref("ArrayBuffer")
   jsxref("SharedArrayBuffer")
   jsxref("RangeError")
   Glossary("Endianness")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("BigInt")
   jsxref("DataView.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/DataView/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/DataView/prototype','Methods')
   SpecName('ESDraft', '#sec-dataview-constructor', 'DataView')
   Spec2('ESDraft')
   SpecName('ES6', '#sec-dataview-constructor', 'DataView')
   Spec2('ES6')
   SpecName('Typed Array')
   Spec2('Typed Array')
   Compat("javascript.builtins.DataView")
   jsxref("Operators/new", "new")
   jsxref("TypeError")
   jsxref("ArrayBuffer")
   jsxref("SharedArrayBuffer")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date (Date)
   EmbedInteractiveExample("pages/js/date-constructor.html")
   jsxref("new")
   RFC(2822)
   anch("Two_digit_years_map_to_1900_-_1999", "example below")
   jsxref("Date.prototype")
   jsxref("Date.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/prototype', 'Methods')
   domxref("window.performance", "Web Performance API", "", 1)
   SpecName('ESDraft', '#sec-date-objects', 'Date')
   Spec2('ESDraft')
   SpecName('ES6', '#sec-date-objects', 'Date')
   Spec2('ES6')
   SpecName('ES5.1', '#sec-15.9', 'Date')
   Spec2('ES5.1')
   SpecName('ES1')
   Spec2('ES1')
   Compat("javascript.builtins.Date", 3)
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString (Date.prototype.toLocaleString())
   EmbedInteractiveExample("pages/js/date-tolocalestring.html")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat', 'Parameters')
   jsxref("undefined")
   jsxref("undefined")
   jsxref("RangeError")
   jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")
   jsxref("DateTimeFormat.prototype.format", "format")
   SpecName('ES1')
   Spec2('ES1')
   SpecName('ES5.1', '#sec-15.9.5.5', 'Date.prototype.toLocaleString')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-date.prototype.tolocalestring', 'Date.prototype.toLocaleString')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-date.prototype.tolocalestring', 'Date.prototype.toLocaleString')
   Spec2('ESDraft')
   SpecName('ES Int 1.0', '#sec-13.3.1', 'Date.prototype.toLocaleString')
   Spec2('ES Int 1.0')
   SpecName('ES Int 2.0', '#sec-13.3.1', 'Date.prototype.toLocaleString')
   Spec2('ES Int 2.0')
   SpecName('ES Int Draft', '#sec-Date.prototype.toLocaleString', 'Date.prototype.toLocaleString')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Date.toLocaleString")
   jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString (Date.prototype.toLocaleTimeString())
   EmbedInteractiveExample("pages/js/date-tolocaletimestring.html")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat', 'Parameters')
   jsxref("undefined")
   jsxref("undefined")
   jsxref("Global_Objects/Date", "Date")
   jsxref("RangeError")
   jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")
   jsxref("DateTimeFormat.prototype.format", "format")
   SpecName('ESDraft', '#sec-date.prototype.tolocaletimestring', 'Date.prototype.toLocaleTimeString')
   Spec2('ESDraft')
   SpecName('ES Int Draft', '#sup-date.prototype.tolocaletimestring', 'Date.prototype.toLocaleTimeString')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Date.toLocaleTimeString")
   jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleDateString (Date.prototype.toLocaleDateString())
   EmbedInteractiveExample("pages/js/date-tolocaledatestring.html")
   anch("Browser compatibility")
   anch("Checking for support for locales and options arguments")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat', 'Parameters')
   jsxref("undefined")
   jsxref("undefined")
   jsxref("Global_Objects/Date", "Date")
   jsxref("RangeError")
   jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")
   jsxref("DateTimeFormat.prototype.format", "format")
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', 'sec-15.9.5.6', 'Date.prototype.toLocaleDateString')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-date.prototype.tolocaledatestring', 'Date.prototype.toLocaleDateString')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-date.prototype.tolocaledatestring', 'Date.prototype.toLocaleDateString')
   Spec2('ESDraft')
   SpecName('ES Int 1.0', '#sec-13.3.2', 'Date.prototype.toLocaleDateString')
   Spec2('ES Int 1.0')
   SpecName('ES Int 2.0', '#sec-13.3.2', 'Date.prototype.toLocaleDateString')
   Spec2('ES Int 2.0')
   SpecName('ES Int Draft', '#sec-Date.prototype.toLocaleDateString', 'Date.prototype.toLocaleDateString')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Date.toLocaleDateString")
   jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp (RegExp)
   EmbedInteractiveExample("pages/js/regexp-constructor.html")
   jsxref("TypeError")
   jsxref("RegExp.prototype")
   jsxref("RegExp.@@species", "get RegExp[@@species]")
   jsxref("RegExp.lastIndex")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/prototype', 'Methods')
   jsxref("Global_Objects/String", "String")
   jsxref("RegExp.prototype.lastIndex")
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.10', 'RegExp')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-regexp-regular-expression-objects', 'RegExp')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-regexp-regular-expression-objects', 'RegExp')
   Spec2('ESDraft')
   Compat("javascript.builtins.RegExp")
   bug(1053944)
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Map (Map)
   Glossary("Primitive", "primitive values")
   jsxref("Array")
   jsxref("Statements/for...of", "for...of")
   jsxref("NaN")
   anch("Browser compatibility")
   jsxref("Object")
   jsxref("String")
   jsxref("Symbol")
   jsxref("Map.prototype.size", "size")
   jsxref("Map.prototype.size")
   jsxref("Map.@@species", "get Map[@@species]")
   jsxref("Map.prototype")
   jsxref("Map.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/Map/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/Map/prototype','Methods')
   jsxref("NaN")
   SpecName('ES2015', '#sec-map-objects', 'Map')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-map-objects', 'Map')
   Spec2('ESDraft')
   Compat("javascript.builtins.Map")
   jsxref("Set")
   jsxref("WeakMap")
   jsxref("WeakSet")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Set (Set)
   Glossary("Primitive", "primitive values")
   EmbedInteractiveExample("pages/js/set-prototype-constructor.html")
   jsxref("NaN")
   jsxref("undefined")
   jsxref("Set.@@species", "get Set[@@species]")
   jsxref("Set.prototype")
   jsxref("Set.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/prototype','Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/prototype','Methods')
   SpecName('ESDraft', '#sec-set-objects', 'Set')
   Spec2('ESDraft')
   SpecName('ES2015', '#sec-set-objects', 'Set')
   Spec2('ES2015')
   Compat("javascript.builtins.Set")
   jsxref("Map")
   jsxref("WeakMap")
   jsxref("WeakSet")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean (Boolean)
   jsxref("null")
   jsxref("NaN")
   jsxref("undefined")
   jsxref("undefined")
   jsxref("null")
   jsxref("Statements/if...else", "if")
   jsxref("Statements/if...else", "if")
   jsxref("Boolean.prototype")
   jsxref("Boolean.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean/prototype', 'Methods')
   SpecName('ES1')
   Spec2('ES1')
   SpecName('ES5.1', '#sec-15.6', 'Boolean')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-boolean-objects', 'Boolean')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-boolean-objects', 'Boolean')
   Spec2('ESDraft')
   Compat("javascript.builtins.Boolean")
   jsxref("Boolean.prototype")
   Glossary("Boolean")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap (WeakMap)
   SectionOnPage("/en-US/docs/Web/JavaScript/Guide/Keyed_collections", "WeakMap object")
   Glossary("Primitive", "Primitive data types")
   jsxref("Symbol")
   jsxref("Map")
   jsxref("WeakMap.prototype")
   jsxref("WeakMap.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/WeakMap/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/WeakMap/prototype','Methods')
   SpecName('ESDraft', '#sec-weakmap-objects', 'WeakMap')
   Spec2('ESDraft')
   SpecName('ES2015', '#sec-weakmap-objects', 'WeakMap')
   Spec2('ES2015')
   Compat("javascript.builtins.WeakMap")
   jsxref("Map")
   jsxref("Set")
   jsxref("WeakSet")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number (Number)
   jsxref("BigInt")
   jsxref("NaN")
   jsxref("Operators/new", "new")
   jsxref("Number.EPSILON")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("Number.MAX_VALUE")
   jsxref("Number.MIN_SAFE_INTEGER")
   jsxref("Number.MIN_VALUE")
   jsxref("Number.NaN")
   jsxref("Number.NEGATIVE_INFINITY")
   jsxref("Number.POSITIVE_INFINITY")
   jsxref("Number.prototype")
   jsxref("Global_Objects/Infinity", "Infinity")
   jsxref("Number.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/prototype', 'Methods')
   jsxref("String")
   jsxref("BigInt")
   jsxref("Date")
   SpecName('ES1')
   Spec2('ES1')
   SpecName('ES5.1', '#sec-15.7', 'Number')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-number-objects', 'Number')
   Spec2('ES6')
   jsxref("Number.EPSILON", "EPSILON")
   jsxref("Number.isFinite", "isFinite")
   jsxref("Number.isInteger", "isInteger")
   jsxref("Number.isNaN", "isNaN")
   jsxref("Number.parseFloat", "parseFloat")
   jsxref("Number.parseInt", "parseInt")
   SpecName('ESDraft', '#sec-number-objects', 'Number')
   Spec2('ESDraft')
   Compat("javascript.builtins.Number")
   jsxref("NaN")
   jsxref("Math")
   jsxref("BigInt")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString (Number.prototype.toLocaleString())
   EmbedInteractiveExample("pages/js/number-tolocalestring.html")
   jsxref("undefined")
   bug(999003)
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat', 'Parameters')
   jsxref("Global_Objects/RangeError", "RangeError")
   jsxref("NumberFormat")
   jsxref("NumberFormat.format")
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.7.4.3', 'Number.prototype.toLocaleString')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-number.prototype.tolocalestring', 'Number.prototype.toLocaleString')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-number.prototype.tolocalestring', 'Number.prototype.toLocaleString')
   Spec2('ESDraft')
   SpecName('ES Int 1.0', '#sec-13.2.1', 'Number.prototype.toLocaleString')
   Spec2('ES Int 1.0')
   SpecName('ES Int 2.0', '#sec-13.2.1', 'Number.prototype.toLocaleString')
   Spec2('ES Int 2.0')
   SpecName('ES Int Draft', '#sec-Number.prototype.toLocaleString', 'Number.prototype.toLocaleString')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Number.toLocaleString")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/parseFloat (Number.parseFloat())
   EmbedInteractiveExample("pages/js/number-parsefloat.html")
   page("en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat", "Parameters")
   page("en-US/docs/Web/JavaScript/Reference/Global_Objects/parseFloat", "Return value")
   SpecName('ES2015', '#sec-number.parsefloat', 'Number.parseFloat')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-number.parsefloat', 'Number.parseFloat')
   Spec2('ESDraft')
   Compat("javascript.builtins.Number.parseFloat")
   jsxref("Number")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/parseInt (Number.parseInt())
   EmbedInteractiveExample("pages/js/number-parseint.html")
   page("en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt", "Parameters")
   page("en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt", "Return value")
   SpecName('ES2015', '#sec-number.parseint', 'Number.parseInt')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-number.parseint', 'Number.parseInt')
   Spec2('ESDraft')
   Compat("javascript.builtins.Number.parseInt")
   jsxref("Number")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String (String)
   jsxref("String.length", "length")
   jsxref("Boolean")
   jsxref("Global_Objects/Number", "Numbers")
   jsxref("Operators/new", "new")
   jsxref("String.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/prototype', 'Methods_unrelated_to_HTML')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/prototype', 'HTML_wrapper_methods')
   jsxref("null")
   jsxref("undefined")
   jsxref("Symbol", "symbols")
   SpecName('ESDraft', '#sec-string-objects', 'String')
   Spec2('ESDraft')
   SpecName('ES2015', '#sec-string-objects', 'String')
   Spec2('ES2015')
   SpecName('ES5.1', '#sec-15.5', 'String')
   Spec2('ES5.1')
   SpecName('ES1')
   Spec2('ES1')
   Compat("javascript.builtins.String",2)
   domxref("DOMString")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare (String.prototype.localeCompare())
   EmbedInteractiveExample("pages/js/string-localecompare.html")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator', 'Parameters')
   jsxref("RangeError")
   jsxref("Global_Objects/Collator", "Intl.Collator")
   jsxref("Collator.prototype.compare", "compare")
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.5.4.9', 'String.prototype.localeCompare')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-string.prototype.localecompare', 'String.prototype.localeCompare')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-string.prototype.localecompare', 'String.prototype.localeCompare')
   Spec2('ESDraft')
   SpecName('ES Int 1.0', '#sec-13.1.1', 'String.prototype.localeCompare')
   Spec2('ES Int 1.0')
   SpecName('ES Int 2.0', '#sec-13.1.1', 'String.prototype.localeCompare')
   Spec2('ES Int 2.0')
   SpecName('ES Int Draft', '#sec-String.prototype.localeCompare', 'String.prototype.localeCompare')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.String.localeCompare")
   jsxref("Global_Objects/Collator", "Intl.Collator")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray (TypedArray)
   EmbedInteractiveExample("pages/js/typedarray-constructor.html")
   jsxref("ArrayBuffer")
   jsxref("ArrayBuffer")
   jsxref("Int8Array")
   jsxref("Uint8Array")
   jsxref("Uint8ClampedArray")
   jsxref("Int16Array")
   jsxref("Uint16Array")
   jsxref("Int32Array")
   jsxref("Uint32Array")
   jsxref("Float32Array")
   jsxref("Float64Array")
   jsxref("BigInt64Array")
   jsxref("BigUint64Array")
   jsxref("TypedArray.BYTES_PER_ELEMENT")
   jsxref("TypedArray.name")
   jsxref("TypedArray.@@species", "get TypedArray[@@species]")
   jsxref("TypedArray.prototype")
   jsxref("TypedArray.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/TypedArray/prototype','Methods')
   SpecName('Typed Array')
   Spec2('Typed Array')
   SpecName('ES6', '#sec-typedarray-objects', 'TypedArray Objects')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-typedarray-objects', 'TypedArray Objects')
   Spec2('ESDraft')
   Compat("javascript.builtins.TypedArray")
   jsxref("Operators/new", "new")
   jsxref("TypeError")
   jsxref("ArrayBuffer")
   jsxref("DataView")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/toLocaleString (TypedArray.prototype.toLocaleString())
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat', 'Parameters')
   SpecName('ES2015', '#sec-%typedarray%.prototype.tolocalestring', 'TypedArray.prototype.toLocaleString')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-%typedarray%.prototype.tolocalestring', 'TypedArray.prototype.toLocaleString')
   Spec2('ESDraft')
   Compat("javascript.builtins.TypedArray.toLocaleString")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer (ArrayBuffer)
   jsxref("DataView")
   EmbedInteractiveExample("pages/js/arraybuffer-constructor.html")
   jsxref("RangeError")
   jsxref("Number.MAX_SAFE_INTEGER")
   jsxref("ArrayBuffer.@@species", "get ArrayBuffer[@@species]")
   jsxref("ArrayBuffer.prototype")
   jsxref("DataView")
   jsxref("ArrayBuffer.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/prototype','Methods')
   jsxref("Global_Objects/Int32Array", "Int32Array")
   SpecName('Typed Array')
   Spec2('Typed Array')
   SpecName('ES6', '#sec-arraybuffer-constructor', 'ArrayBuffer')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-arraybuffer-constructor', 'ArrayBuffer')
   Spec2('ESDraft')
   Compat("javascript.builtins.ArrayBuffer")
   jsxref("Operators/new", "new")
   jsxref("TypeError")
   jsxref("SharedArrayBuffer")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Object (Object)
   jsxref("null")
   jsxref("undefined")
   jsxref("Object.prototype")
   jsxref("Object.entries")
   jsxref("Object.prototype")
   **page("/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/prototype", "Properties")
   **page("/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/prototype", "Methods")
   jsxref("Boolean")
   SpecName('ESDraft', '#sec-object-objects', 'Object')
   Spec2('ESDraft')
   SpecName('ES6', '#sec-object-objects', 'Object')
   Spec2('ES6')
   SpecName('ES5.1', '#sec-15.2', 'Object')
   Spec2('ES5.1')
   SpecName('ES1')
   Spec2('ES1')
   Compat("javascript.builtins.Object")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Error (Error)
   JSxRef("Error.prototype")
   JSxRef("Operators/new", "new")
   JSxRef("EvalError")
   JSxRef("InternalError")
   JSxRef("RangeError")
   JSxRef("ReferenceError")
   JSxRef("SyntaxError")
   JSxRef("TypeError")
   JSxRef("URIError")
   JSxRef("Error.prototype")
   JSxRef("Error.prototype.stack", "stack")
   **page('/en-US/docs/JavaScript/Reference/Global_Objects/Error/prototype', 'Description')
   **page('/en-US/docs/JavaScript/Reference/Global_Objects/Error/prototype', 'Properties', '', '', 3)
   **page('/en-US/docs/JavaScript/Reference/Global_Objects/Error/prototype', 'Methods')
   JSxRef("Statements/throw", "throw")
   JSxRef("Statements/try...catch", "try...catch")
   JSxRef("Object.prototype.constructor", "constructor")
   JSxRef("Operators/instanceof", "instanceof")
   SpecName('ESDraft', '#sec-error-objects', 'Error')
   Spec2('ESDraft')
   SpecName('ES2015', '#sec-error-objects', 'Error')
   Spec2('ES2015')
   SpecName('ES5.1', '#sec-15.11', 'Error')
   Spec2('ES5.1')
   SpecName('ES1')
   Spec2('ES1')
   Compat("javascript.builtins.Error")
   JSxRef("Error.prototype")
   JSxRef("Statements/throw", "throw")
   JSxRef("Statements/try...catch", "try...catch")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy (Proxy)
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/handler', 'Methods')
   SpecName('ES2015', '#sec-proxy-objects', 'Proxy')
   Spec2('ES2015')
   SpecName('ES2016', '#sec-proxy-objects', 'Proxy')
   Spec2('ES2016')
   SpecName('ES2017', '#sec-proxy-objects', 'Proxy')
   Spec2('ES2017')
   SpecName('ESDraft', '#sec-proxy-objects', 'Proxy')
   Spec2('ESDraft')
   Compat("javascript.builtins.Proxy", 2)
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError (URIError)
   jsxref("URIError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError/prototype', 'Methods')
   SpecName('ES3', '#sec-15.11.6.6', 'URIError')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.11.6.6', 'URIError')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-native-error-types-used-in-this-standard-urierror', 'URIError')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-native-error-types-used-in-this-standard-urierror', 'URIError')
   Spec2('ESDraft')
   Compat("javascript.builtins.URIError")
   jsxref("Error")
   jsxref("URIError.prototype")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError (TypeError)
   jsxref("TypeError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError/prototype', 'Methods')
   SpecName('ES3', '#sec-15.11.6.5', 'TypeError')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.11.6.5', 'TypeError')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-native-error-types-used-in-this-standard-typeerror', 'TypeError')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-native-error-types-used-in-this-standard-typeerror', 'TypeError')
   Spec2('ESDraft')
   Compat("javascript.builtins.TypeError")
   jsxref("Error")
   jsxref("TypeError.prototype")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError (SyntaxError)
   jsxref("SyntaxError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError/prototype', 'Methods')
   SpecName('ESDraft', '#sec-native-error-types-used-in-this-standard-syntaxerror', 'SyntaxError')
   Spec2('ESDraft')
   SpecName('ES6', '#sec-native-error-types-used-in-this-standard-syntaxerror', 'SyntaxError')
   Spec2('ES6')
   SpecName('ES5.1', '#sec-15.11.6.4', 'SyntaxError')
   Spec2('ES5.1')
   SpecName('ES3')
   Spec2('ES3')
   Compat("javascript.builtins.SyntaxError")
   jsxref("Error")
   jsxref("SyntaxError.prototype")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError (RangeError)
   jsxref("Array")
   jsxref("RangeError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError/prototype', 'Methods')
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.11.6.2', 'RangeError')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-native-error-types-used-in-this-standard-rangeerror', 'RangeError')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-native-error-types-used-in-this-standard-rangeerror', 'RangeError')
   Spec2('ESDraft')
   Compat("javascript.builtins.RangeError")
   jsxref("Error")
   jsxref("RangeError.prototype")
   jsxref("Array")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError (ReferenceError)
   jsxref("ReferenceError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError/prototype', 'Methods')
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.11.6.3', 'ReferenceError')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-native-error-types-used-in-this-standard-referenceerror', 'ReferenceError')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-native-error-types-used-in-this-standard-referenceerror', 'ReferenceError')
   Spec2('ESDraft')
   Compat("javascript.builtins.ReferenceError")
   jsxref("Error")
   jsxref("ReferenceError.prototype")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError (EvalError)
   jsxref("EvalError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError/prototype', 'Methods')
   SpecName('ES3')
   Spec2('ES3')
   SpecName('ES5.1', '#sec-15.11.6.1', 'EvalError')
   Spec2('ES5.1')
   SpecName('ES6', '#sec-native-error-types-used-in-this-standard-evalerror', 'EvalError')
   Spec2('ES6')
   SpecName('ESDraft', '#sec-native-error-types-used-in-this-standard-evalerror', 'EvalError')
   Spec2('ESDraft')
   Compat("javascript.builtins.EvalError")
   jsxref("Error")
   jsxref("EvalError.prototype")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator (Intl.Collator)
   EmbedInteractiveExample("pages/js/intl-collator.html")
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_identification_and_negotiation", 1)
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_negotiation", 1)
   jsxref("Collator.prototype", "Intl.Collator.prototype")
   **page('en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator/prototype', 'Properties')
   **page('en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator/prototype', 'Methods')
   SpecName('ES Int 1.0', '#sec-10.1', 'Intl.Collator')
   Spec2('ES Int 1.0')
   SpecName('ES Int 2.0', '#sec-10.1', 'Intl.Collator')
   Spec2('ES Int 2.0')
   SpecName('ES Int Draft', '#collator-objects', 'Intl.Collator')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Intl.Collator")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat (Intl.NumberFormat)
   EmbedInteractiveExample("pages/js/intl-numberformat.html")
   jsxref("Intl", "Intl page", "#Locale_identification_and_negotiation", 1)
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_negotiation", 1)
   jsxref("NumberFormat.prototype", "Intl.NumberFormat.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat/prototype', 'Methods')
   SpecName('ES Int 1.0', '#sec-11.1', 'Intl.NumberFormat')
   Spec2('ES Int 1.0')
   SpecName('ES Int 2.0', '#sec-11.1', 'Intl.NumberFormat')
   Spec2('ES Int 2.0')
   SpecName('ES Int Draft', '#numberformat-objects', 'Intl.NumberFormat')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Intl.NumberFormat")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat (Intl.DateTimeFormat)
   EmbedInteractiveExample("pages/js/intl-datetimeformat.html")
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_identification_and_negotiation", 1)
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_negotiation", 1)
   jsxref("undefined")
   jsxref("undefined")
   jsxref("DateTimeFormat.prototype", "Intl.DateTimeFormat.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype', 'Methods')
   SpecName('ES Int Draft', '#datetimeformat-objects', 'Intl.DateTimeFormat')
   Spec2('ES Int Draft')
   SpecName('ES Int 2.0', '#sec-12.1', 'Intl.DateTimeFormat')
   Spec2('ES Int 2.0')
   SpecName('ES Int 1.0', '#sec-12.1', 'Intl.DateTimeFormat')
   Spec2('ES Int 1.0')
   Compat("javascript.builtins.Intl.DateTimeFormat")
   EmbedTest262ReportResultsTable("Intl.DateTimeFormat-datetimestyle")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/formatRange (Intl.DateTimeFormat.prototype.formatRange())
   jsxref("DateTimeFormat", "Intl.DateTimeFormat")
   EmbedInteractiveExample("pages/js/intl-datetimeformat-prototype-formatrange.html")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet (WeakSet)
   jsxref("Set")
   jsxref("Set")
   jsxref("WeakSet.prototype")
   jsxref("WeakSet.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/WeakSet/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/WeakSet/prototype','Methods')
   SpecName('ES2015', '#sec-weakset-objects', 'WeakSet')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-weakset-objects', 'WeakSet')
   Spec2('ESDraft')
   Compat("javascript.builtins.WeakSet")
   jsxref("Map")
   jsxref("Set")
   jsxref("WeakMap")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/InternalError (InternalError)
   jsxref("InternalError.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/InternalError/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/InternalError/prototype', 'Methods')
   Compat("javascript.builtins.InternalError")
   jsxref("Error")
   jsxref("InternalError.prototype")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol (Symbol)
   Glossary("Primitive", "primitive data type")
   EmbedInteractiveExample("pages/js/symbol-constructor.html")
   jsxref("Operators/new", "new")
   jsxref("TypeError")
   jsxref("Symbol.prototype")
   jsxref("Symbol.iterator")
   jsxref("Symbol.asyncIterator")
   jsxref("Symbol.match")
   jsxref("Symbol.matchAll")
   jsxref("Symbol.replace")
   jsxref("Symbol.search")
   jsxref("Symbol.split")
   jsxref("Symbol.hasInstance")
   jsxref("Operators/instanceof", "instanceof")
   jsxref("Symbol.isConcatSpreadable")
   jsxref("Symbol.unscopables")
   jsxref("Symbol.species")
   jsxref("Symbol.toPrimitive")
   jsxref("Symbol.toStringTag")
   jsxref("Symbol.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/Symbol/prototype','Methods')
   jsxref("Operators/typeof", "typeof")
   jsxref("TypeError")
   jsxref("TypeError")
   SpecName('ES2015', '#sec-symbol-objects', 'Symbol')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-symbol-objects', 'Symbol')
   Spec2('ESDraft')
   Compat("javascript.builtins.Symbol")
   jsxref("Operators/typeof", "typeof")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction (GeneratorFunction)
   jsxref("Statements/function*", "generator function")
   jsxref("Statements/function*", "generator function")
   jsxref("Statements/function*", "function* expression")
   jsxref("Statements/function*", "generator function")
   jsxref("Global_Objects/eval", "eval")
   jsxref("GeneratorFunction.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/GeneratorFunction/prototype', 'Properties')
   jsxref("GeneratorFunction.prototype")
   SpecName('ES2015', '#sec-generatorfunction-objects', 'GeneratorFunction')
   Spec2('ES2015')
   SpecName('ESDraft', '#sec-generatorfunction-objects', 'GeneratorFunction')
   Spec2('ESDraft')
   Compat("javascript.builtins.GeneratorFunction")
   jsxref("Statements/function*", "function* function")
   jsxref("Operators/function*", "function* expression")
   jsxref("Global_Objects/Function", "Function")
   jsxref("Statements/function", "function statement")
   jsxref("Operators/function", "function expression")
   jsxref("Functions_and_function_scope", "Functions and function scope", "", 1)
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer (SharedArrayBuffer)
   jsxref("ArrayBuffer")
   EmbedInteractiveExample("pages/js/sharedarraybuffer-constructor.html")
   jsxref("SharedArrayBuffer")
   jsxref("ArrayBuffer")
   jsxref("Atomics", "atomic", "", 1)
   jsxref("Operators/new", "new")
   jsxref("TypeError")
   jsxref("SharedArrayBuffer.prototype")
   jsxref("SharedArrayBuffer.prototype")
   **page('en-US/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/prototype','Properties')
   **page('en-US/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/prototype','Methods')
   SpecName('ESDraft', '#sec-sharedarraybuffer-objects', 'SharedArrayBuffer')
   Spec2('ESDraft')
   SpecName('ES8', '#sec-sharedarraybuffer-objects', 'SharedArrayBuffer')
   Spec2('ES8')
   Compat("javascript.builtins.SharedArrayBuffer")
   jsxref("Atomics")
   jsxref("ArrayBuffer")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction (AsyncFunction)
   jsxref("Statements/async_function", "async function")
   jsxref("Statements/async_function", "async function")
   jsxref("Statements/async_function", "async function expression")
   jsxref("Statements/async_function", "async functions")
   jsxref("Global_Objects/eval", "eval")
   jsxref("AsyncFunction.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncFunction/prototype', 'Properties')
   jsxref("AsyncFunction.prototype")
   SpecName('ESDraft', '#sec-async-function-objects', 'AsyncFunction object')
   Spec2('ESDraft')
   Compat("javascript.builtins.AsyncFunction")
   jsxref("Statements/async_function", "async function function")
   jsxref("Operators/async_function", "async function expression")
   jsxref("Global_Objects/Function", "Function")
   jsxref("Statements/function", "function statement")
   jsxref("Operators/function", "function expression")
   jsxref("Functions_and_function_scope", "Functions and function scope", "", 1)
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module (WebAssembly.Module)
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module/prototype', 'Properties')
   Spec2('WebAssembly JS')
   Compat("javascript.builtins.WebAssembly.Module")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance (WebAssembly.Instance)
   jsxref("WebAssembly.Module")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/prototype', 'Properties')
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance/prototype', 'Methods')
   SpecName('WebAssembly JS', '#webassemblyinstance-objects', 'Instance')
   Spec2('WebAssembly JS')
   Compat("javascript.builtins.WebAssembly.Instance")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Global (WebAssembly.Global)
   jsxref("WebAssembly.Module")
   domxref("USVString")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Global/prototype', 'Properties')
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Global/prototype', 'Methods')
   Spec2('WebAssembly JS')
   Compat("javascript.builtins.WebAssembly.Global")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules (Intl.PluralRules)
   jsxref("Intl", "Intl page", "#Locale_identification_and_negotiation", 1)
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_negotiation", 1)
   jsxref("PluralRules.prototype", "Intl.PluralRules.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/PluralRules/prototype', 'Methods')
   Spec2('ES Int Draft')
   Compat("javascript.builtins.Intl.PluralRules")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt/toLocaleString (BigInt.prototype.toLocaleString())
   EmbedInteractiveExample("pages/js/bigint-tolocalestring.html")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat', 'Parameters')
   jsxref("NumberFormat")
   jsxref("NumberFormat.format")
   Compat("javascript.builtins.BigInt.toLocaleString")
**DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat (Intl.RelativeTimeFormat)
   EmbedInteractiveExample("pages/js/intl-relativetimeformat.html")
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_identification_and_negotiation", 1)
   jsxref("RelativeTimeFormat.prototype", "Intl.RelativeTimeFormat.prototype")
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/prototype', 'Properties')
   **page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/RelativeTimeFormat/prototype', 'Methods')
   Compat("javascript.builtins.Intl.RelativeTimeFormat")
DOC: /en-US/docs/Web/JavaScript/Reference/Global_Objects/ListFormat (Intl.ListFormat)
   EmbedInteractiveExample("pages/js/intl-listformat.html")
   jsxref("Global_Objects/Intl", "Intl page", "#Locale_identification_and_negotiation", 1)
   jsxref("ListFormat.prototype", "Intl.ListFormat.prototype")
   Compat("javascript.builtins.Intl.ListFormat")
   page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')
DOC: /en-US/docs/Web/JavaScript/New_in_JavaScript/Firefox_JavaScript_changelog (Firefox JavaScript changelog)
   jsSidebar("New_in_JS")
   page('en-US/docs/Mozilla/Firefox/Releases/52','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/51','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/50','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/49','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/48','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/47','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/46','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/45','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/44','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/43','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/42','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/41','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/40','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/39','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/38','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/37','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/36','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/35','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/34','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/33','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/32','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/31','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/30','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/29','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/28','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/27','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/26','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/25','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/24','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/23','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/22','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/21','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/20','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/19','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/18','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/17','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/16','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/15','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/14','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/13','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/12','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/11','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/10','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/9','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/8','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/7','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/6','JavaScript')
   page('en-US/docs/Mozilla/Firefox/Releases/5','JavaScript')
DOC: /en-US/docs/Web/JavaScript/Guide/Introduction (Introduction)
   jsSidebar("JavaScript Guide")
   PreviousNext("Web/JavaScript/Guide", "Web/JavaScript/Guide/Grammar_and_types")
   Glossary("WWW")
   Glossary("HTML")
   page("/en-US/docs/Tools/Web_Console/The_command_line_interpreter", "Multi-line_mode")
   PreviousNext("Web/JavaScript/Guide", "Web/JavaScript/Guide/Grammar_and_types")
DOC: /en-US/docs/Web/JavaScript/Guide/Indexed_collections (Indexed collections)
   jsSidebar("JavaScript Guide")
   PreviousNext("Web/JavaScript/Guide/Regular_Expressions", "Web/JavaScript/Guide/Keyed_Collections")
   jsxref("Array")
   jsxref("TypedArray")
   jsxref("Statements/for...in","for...in")
   jsxref("Array.of")
   jsxref("Statements/for...in","for...in")
   jsxref("Array")
   domxref("window")
   domxref("NodeList")
   jsxref("Functions/arguments","arguments")
   jsxref("Global_Objects/Function/length","length")
   jsxref("Array")
   jsxref("ArrayBuffer")
   jsxref("ArrayBuffer")
   jsxref("DataView")
   page("/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray", "TypedArray_objects")
   jsxref("TypedArray")
   PreviousNext("Web/JavaScript/Guide/Regular_Expressions", "Web/JavaScript/Guide/Keyed_Collections")
DOC: /en-US/docs/Web/JavaScript/Guide/Using_promises (Using Promises)
   jsSidebar("JavaScript Guide")
   PreviousNext("Web/JavaScript/Guide/Details_of_the_Object_Model", "Web/JavaScript/Guide/Iterators_and_Generators")
   jsxref("Promise")
   domxref("window")
   domxref("Worker")
   domxref("Window.rejectionhandled_event", "rejectionhandled")
   domxref("Window.unhandledrejection_event", "unhandledrejection")
   domxref("PromiseRejectionEvent")
   domxref("PromiseRejectionEvent.promise", "promise")
   domxref("PromiseRejectionEvent.reason", "reason")
   Glossary("Node.js")
   domxref("Window.unhandledrejection_event", "unhandledrejection")
   jsxref("Promise")
   page("/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide", "Ensuring_ordering_on_conditional_use_of_promises")
   PreviousNext("Web/JavaScript/Guide/Details_of_the_Object_Model", "Web/JavaScript/Guide/Iterators_and_Generators")
Elchi3 commented 4 years ago

There is a lot to unpack for me in here, but I'm not really disagreeing with anything said or discussed. Very nice work, Will!

On the page macro:

But it is used quite extensively in the JS docs to include instance properties and methods from the corresponding Foo/prototype page.

Yes, but I'm planning to get rid of this completely. So, I guess it is "replace" and the implementation of "replace" has been hashed out in London already: https://github.com/mdn/sprints/issues/2571. For the remaining usage of {{page}} (that are not Foo/prototype pages), I think we probably remove or render. Need to see this case by case, but I don't want to support transclusion unnecessarily at this point.

On the EmbedTest262ReportResultsTable macro:

I'd be happy to remove it, but it is very new (mdn/kumascript#1245). As I understand it, it is experimental and I don't know what the status of the experiment is. I think Florian's input is needed here.

We need to get results back from Bocoup and then we need to make a call. I agree with y'all about the questionable usefulness, but I'd like to also give the metrics a chance to speak for themselves first.

On docstatus, index, or any "meta" pages:

Let's remove all this. If needed, we will have to re-invent these tools.

wbamberg commented 4 years ago

Thanks for the reviews everyone. I'm going to summarize our choices below and close this issue.

Remove:

Render:

Replace:

To do

[0] many calls to this macro will be removed in the course of https://github.com/mdn/sprints/issues/2571 [1] already supported in stumptown

wbamberg commented 4 years ago

We did some work on this in Berlin, and:

So I'd like to reopen this issue with an updated proposal:

Retain/replace:

Non-standard_Header [0] Obsolete_Header [0] deprecated_header [0] SeeCompatTable [0] JSRef JsSidebar PreviousNext Next Previous js_property_attributes EmbedInteractiveExample EmbedLiveSample SpecName Spec2 ListSubPages

Render:

jsxref [1] bug [1] Glossary [1] domxref [1] page

Remove

Draft non-standard_inline [2] Obsolete_inline [2] ReadOnlyInline [2] experimental_inline [2] deprecated_inline [2] optional_inline [2] Index

To do:

EmbedTest262ReportResultsTable

Notes

[0] These are all what we sometimes call "banners". They create a banner across the page warning that the item is (for example) deprecated. See e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Expression_closures for a nice pile of these things. We had triaged these as "remove", but Florian pointed out that without them, it would sometimes be hard to notice this important attribute. It should be present in BCD, but the way this is represented in the rendered page makes it very easy to miss. Currently it's a problem that this attribute is recorded in two or more places - the BCD itself and the macro call. Ideally, the attribute would only be recorded in BCD, and the renderer would add the header/banner automatically. So the proposal is to keep these macros in Kuma, and update stumptown so it can automatically set the header based on the BCD. Then the scraper's "replace" algorithm is just to remove the macros.

[1] These are xrefs. Before rendering them, we would like to update the macro so it does not include the title summary.

[2] These are what we sometimes call "badges". They are supposed to convey similar information to banners, but appear next to the link to the page for the item, rather than on the page itself. They are typically rendered as icons like 👎 . I think it would be OK to just remove these - anyone clicking the link will see that the item is deprecated.

@Elchi3 , @ddbeck , comments?

ddbeck commented 4 years ago

I'm happy with this update. I'm going to spend some more time this week on improving the linter in the hopes that we'll reliably catch macros (I think I've got an approach that's workable).

Elchi3 commented 4 years ago

Makes sense to me. Thanks Will for capturing this discussion so nicely!

wbamberg commented 4 years ago

{{page}} is actually annoying and I think will involve case-by-case work. Very often it seems like it could be replaced with a link. Sometimes (e.g. in https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference$edit ) it should be replaced by some landing page magic. Sometimes probably it should be rendered.

Elchi3 commented 4 years ago

[1] These are xrefs. Before rendering them, we would like to update the macro so it does not include the title summary.

I've filed this as https://github.com/mdn/sprints/issues/2787 now.

wbamberg commented 4 years ago

We've discussed this elsewhere, but for the record: optional_inline, and (less so, but for similar reasons) readonlyinline should not be triaged as "remove". Consensus was to render them out, and, at least initially, embedding the rendered HTML in the Markdown.

We might want to remove this as some future cleanup operation. "optional_inline" is called 198 times in the JS docs, and from 689 pages in all our docs (en-US). Which, while it is a lot, seems fewer than we would expect if it were being used consistently.

wbamberg commented 4 years ago

Updated triage list, based on changes mentioned in https://github.com/mdn/sprints/issues/2520#issuecomment-593684240:

Retain/replace:

Non-standard_Header Obsolete_Header deprecated_header SeeCompatTable JSRef JsSidebar PreviousNext Next Previous js_property_attributes EmbedInteractiveExample EmbedLiveSample SpecName Spec2 ListSubPages

Render:

jsxref bug Glossary domxref page - this macro is gone from the JS docs: https://github.com/mdn/sprints/issues/2798. Thanks Florian! optional_inline ReadOnlyInline

Remove

Draft non-standard_inline Obsolete_inline experimental_inline deprecated_inline Index

To do:

EmbedTest262ReportResultsTable

jmswisher commented 4 years ago

Taking this issue out of the Tracy Chapman milestone, so I can close that milestone.

peterbe commented 3 years ago

Regarding the list of "Remove" (above)... Since https://github.com/mdn/yari/pull/2746 it's now a flaw to use one of the KS macros whose code (.ejs file) includes the line mdn.deprecated(). And it's a fixable flaw so it will automatically remove the KS macro. So, to tackle the KS macros that should be removed, you just need to update the .ejs file to have that line (look at https://github.com/mdn/yari/blob/8cedcfd125eb88b594c10a7e27b24905a2ccf7ff/kumascript/macros/fx_minversion_inline.ejs#L20 for an example) So let's compare that list with what we've got:

(in other words, at the time of writing, all of these macros render out and are not cleaned up with the flaw-system)

A tricky one is Index. If that macro should be removed what should happen to all the pages whose slug ends with Index. E.g. https://github.com/mdn/content/blob/main/files/en-us/web/api/index/index.html

peterbe commented 3 years ago

Also, can we not say that this issue is complete and can closed? If Will's comment above is the final verdict, then that answers the issue's title and the next action is to explode this into fresh new smaller atoms of issues that we can work against.

mirai-anime commented 3 years ago

(animation) ซึ่ง{มา|มาหา|มาริ|มาสู่|ลงมา}{ริ|ริอ่าน}{ดำเนิน|ไป|จาก|เดินทาง|เคลื่อน|เดิน|เคลื่อนที่} ภาษาฝรั่งเศส อานีเม่ (anim?) {ถ่าย|ขนถ่าย|ขน|ขนย้าย|สำเนา|คัดลอก|ขี้|อึ|ถ่ายอุจจาระ|ขับถ่าย|ระบาย|โยกย้าย}{ความหมาย|ความนัย|คำจำกัดความ|คำนิยาม|คำอธิบายศัพท์|ความสำคัญ|นัย}{เหมา|ว่า|ว่าจ้าง}{เคลื่อน|ขับเคลื่อน|ขับ|เขยื้อน|เขยิบ|ขยับ|ย้าย|เลื่อน|เคลื่อนตัว|เคลื่อนไหว|ขยับเขยื้อน|ไป|จาก|เดินทาง|ดำเนิน|เดินเครื่อง|ติดเครื่อง|กระดิกกระเดี้ย|กรีธา|ยก} {หรือ|ใช่ไหม|หรือไม่|ไม่ใช่หรือ|เหรอ|หรือว่า|ไม่ก็|หรือไม่ก็}{ไม่|มิ|เปล่า}ก็{ทัศนียภาพ|ทิวทัศน์|วิว|ทิวภาพ|ขอบฟ้า|ภาพ}{ขยับเขยื้อน|เคลื่อนไหว|เคลื่อน} {แต่ว่า|ทว่า|แต่ทว่า|แต่|แต่ถ้าว่า|เสียแต่ว่า|แม้ว่า}{ได้|ได้รับ|ได้มา|หาได้|จัดหามา|คว้า}{กลาย|เปลี่ยนไป|แปรไป|กลับกลาย|เปลี่ยนแปลง|กลายเป็น}{เป็นนัย|โดยปริยาย|ใบ้|แย้มพราย}{หมด|สิ้นสุด|จบ|ถึงที่สุด|รวด|ทั้งหมด|เรียบ|ไม่เหลือ|เกลี้ยง|ขาดมือ|ตรึก|สิ้น|เปลือง|เจ๊ง|ล้ม|ชิ่น|สูญสิ้น|ว่างเปล่า|ล่มจม|หมดสิ้น}{ทาง|ลู่|แนว|ทางวิ่ง|เลน|โอกาส|ช่อง|จังหวะ|ลู่ทาง|ลาดเลา|แนวทาง|วิถีทาง|วิธี|วิธีการ|แบบ|วิถี|เส้นทาง|สาย|ถนน|มารค|มรรค|มรรคา|ถนนหนทาง|ทำนองคลองธรรม|แบบอย่าง|ทิศ|ทิศานุทิศ|เบื้อง|ข้าง|ทิศา|ด้าน|ทางสัญจร|กระแส|ช่องทาง|ตรอก|ซอย|ทางผ่าน|ทางเดิน|ทางแคบ|ครรลอง|หนทาง|มุข}{ไป|เสด็จ|อยู่|จาก|เดินทาง|เคลื่อน|ดำเนิน|เสด็จพระราชดำเนิน|คลาไคล|จร|เที่ยวไป|เดิน|เคลื่อนที่|เจียร|จากไป}{มี|ประกอบด้วย|กอบด้วย|มีอยู่}{ชีวิต|ปากท้อง|ชีพ|ชีวะ|ชีวา|ชีวี|ชีวัน|ชีวิตินทรีย์}{วาจา|คำพูด|ถ้อยคำ|วลี|คำกล่าว|คำ|วจี}{เท่านั้น|แต่|เฉพาะ|อย่างเดียว|เพียงนั้น|แค่นั้น|ขนาดนั้น}{ข้าวของ|เครื่องใช้|ของ|สิ่งของ|ข้าวของเครื่องใช้|ของใช้}{เครื่องใช้|ข้าวของ|ของ|สิ่งของ|ข้าวของเครื่องใช้|ของใช้|เครื่องบริขาร|บริภัณฑ์|เครื่องใช้สอย|เครื่องอุปโภค|ของอุปโภค|สิ่งของเครื่องใช้|ที่|ภาชนะ}ภาษาญี่ปุ่น {ระวาง|ที่|ตำแหน่ง|ทำเนียบ}{ใช้|ชดใช้|ชำระคืน|กิน|เปลือง|ใช้คืน}{คืน|ส่งกลับ|ส่งคืน|กลับคืน|กลับ}{พาหะ|ตัวนำ|สื่อ}{แม้|ถ้าแม้|แม้ว่า|ถึงแม้|แม้น|หาก|ถ้า|ถ้าหาก|สมมติว่า|ผิ|ถึง|ทั้งที่|ทั้งๆ ที่|ถึงแม้ว่า|ขนาดที่}{พาหะ|ตัวนำ|สื่อ}{จอเงิน|ภาพยนตร์|หนัง|จอภาพยนตร์}{ภาพ|ทัศนียภาพ|ทิวภาพ|ทิวทัศน์}{ล้อ|ล้อรถ|ลูกล้อ|แหย่|เย้า|ยั่วเย้า|ยั่ว|หยอกล้อ} (animated media

Elchi3 commented 2 years ago

@schalkneethling asked for input on this. So here are my thoughts.

I think we have less macros these days but not all can be removed yet. (I haven't done a grep on macro usage but suspecting the list above is more or less accurate).

teoli2003 commented 2 years ago
SphinxKnight commented 2 years ago

If I may (re: mdn/translated-content)

wbamberg commented 2 years ago

Link macros (jsxref, previous, previousnext, glossary, bug) can probably be replaced by plain markdown links.

I've been thinking about this a bit recently. It feels like something changed in Yari that made the syntax for xrefs more complicated. I think there used to be a reasonable argument that xref syntax was simpler even than Markdown links, but often these days I find myself writing something like:

{{jsxref("Operators/await", "await")}}

and wondering in which ways that is better, syntactically, than:

[`await`](/en-US/docs/Web/JavaScript/Reference/Operators/await)

As people have said upthread: given a consensus that we want to do this, it would be quite a mechanical task. According to the KS landscape doc this is the second biggest group of macros (almost certainly the biggest now, since most of the "internal" group should have been removed or be removable).

{{previous}} and {{previousnext}} are different though because they want particular styling, so plain Markdown won't work. Stumptown had an abstraction called a "chapter list" which was intended to enable auto-generation of these types of links: https://github.com/mdn/stumptown-content/issues/265.

teoli2003 commented 2 years ago

We have deleted/deprecated a lot of macros since then. But this is still valid, even if {{page}}, {{SpecName}}and {{Spec2}} are now gone from mdn/content. (And many others are now gone).

Dealing with banners would be a contained (and doable) project (on the dev side), to move this project forward, while we continue to remove the use of the long tail of macros.

Sidebars macros depend on the page-type project (adding page-type to the YAML header) and the renaming of the page (which will add another YAML header). Once this is done, we should be mature enough to start a sidebar project.

* Banners (non-standard, deprecated, seeCompatTable) should be driven by BCD (proposal: [OWD project proposal: Generate "experimental" banners from BCD openwebdocs/project#81](https://github.com/openwebdocs/project/issues/81))

* Sidebars (JSRef, JsSidebar) need a sidebar project (there was once talk to have yaml files drive sidebar generation)

* Interactive Examples may want to see how it's possibly to embed them without KS?

* Link macros (jsxref, previous, previousnext, glossary, bug) can probably be replaced by plain markdown links.
schalkneethling commented 2 years ago

We have deleted/deprecated a lot of macros since then. But this is still valid, even if {{page}}, {{SpecName}}and {{Spec2}} are now gone from mdn/content. (And many others are now gone).

Dealing with banners would be a contained (and doable) project (on the dev side), to move this project forward, while we continue to remove the use of the long tail of macros.

Sidebars macros depend on the page-type project (adding page-type to the YAML header) and the renaming of the page (which will add another YAML header). Once this is done, we should be mature enough to start a sidebar project.

* Banners (non-standard, deprecated, seeCompatTable) should be driven by BCD (proposal: [OWD project proposal: Generate "experimental" banners from BCD openwebdocs/project#81](https://github.com/openwebdocs/project/issues/81))

* Sidebars (JSRef, JsSidebar) need a sidebar project (there was once talk to have yaml files drive sidebar generation)

* Interactive Examples may want to see how it's possibly to embed them without KS?

* Link macros (jsxref, previous, previousnext, glossary, bug) can probably be replaced by plain markdown links.

I have no idea what is going on. There are a LOT of issues being closed by the github-actions bot.

caugner commented 4 weeks ago

Most of these macros have already been replaced, and this is obsolete with the rari work, so I'm closing this as resolved.