<p>The ECMAScript specification and its drafts are very accessible, but they're formatted a bit oddly -- case in point, the current version of <a href="https://tc39.es/ecma262/multipage/abstract-operations.html#sec-tobigint" rel="nofollow noreferrer">the ToBigInt abstract operation</a> uses three fonts:</p>
<p><a href="https://i.sstatic.net/p6Csx.png" rel="nofollow noreferrer"><img src="https://i.sstatic.net/p6Csx.png" alt="A screenshot of the specification for the ToBigInt abstract operation. It uses three different fonts and multiple text colors." /></a></p>
<ul>
<li>The base (serif) font</li>
<li>A sans-serif font for the word &quot;NUMBER&quot;</li>
<li>A monospace font for the BigInt literals <strong><code>1n</code></strong> and <strong><code>0n</code></strong></li>
</ul>
<p>Several other sections (though not this particular one) feature things such as @@wellKnownSymbol, [[InternalSlot]], and <em>%BuiltInClass%</em>.</p>
<p>While some of this formatting is helpful, such as to separate internal slots from properties visible to the JavaScript code, it's confusing especially to beginners, and the use of several fonts means it cannot be reproduced in e.g. markdown. Why did they choose to format it in this way?</p>

<javascript><specification>
Why is the ECMAScript specification formatted the way it is?
CC BY-SA 4.0
2023-09-23T04:08:38.527Z
Why do you care about reproducing that typesetting in Markdown?
Bergi
CC BY-SA 4.0
2023-09-23T05:50:32.823Z
@Bergi Mostly when quoting it elsewhere, as many other sites (here, Reddit, Discord) use Markdown for formatting.
Bbrk24
CC BY-SA 4.0
2023-09-23T09:04:33.853Z
*"it's confusing especially to beginners"* - it's not meant for beginners. I would likewise strongly recommend against a beginner reading the Java Language Specification. Anything a beginner might want to know is explained elsewhere; the spec is intended mainly as a reference for implementors and language lawyers.
kaya3
CC BY-SA 4.0
2023-09-23T16:11:32.253Z
ECMAScript specs are full of WTFs. It only makes sense the formatting would follow this tradition too.
Eric Duminil
CC BY-SA 4.0
2023-09-30T10:13:37.113Z
To be clear: the question is "what semantic information is conveyed by the font choice, or intended to be conveyed that way"? Or is it "why did the documentation writers think that this would be a good idea"? Or just what exactly?
Karl Knechtel
CC BY-SA 4.0
2023-09-30T16:14:42.547Z
@KarlKnechtel The latter.
Bbrk24
CC BY-SA 4.0
2023-09-30T16:32:53.957Z
@Bbrk24 Well the answer to that is "*because it **is** a good idea*", no? The spec is written for implementers who care about such details, it is not a tutorial for beginners.
Bergi
CC BY-SA 4.0
2023-10-01T07:37:43.100Z
It seems like the one answer you got so far inferred the former, so there is some amount of ambiguity here.
Karl Knechtel
CC BY-SA 4.0
2023-10-02T06:01:48.500Z
I don't see anything wrong with this question. Voting to reopen.
CPlus
<p>The ordinary bold text is used for ECMAScript values, while the monospace is for source text, as specified in Section</p>
<blockquote>
<p><a href="https://tc39.es/ecma262/multipage/notational-conventions.html#sec-value-notation" rel="nofollow noreferrer">5.2.6 Value Notation</a></p>
<p>In this specification, ECMAScript language values are displayed in <strong>bold</strong>. Examples include <strong>null</strong>, <strong>true</strong>, or <strong>&quot;hello&quot;</strong>. These are distinguished from ECMAScript source text such as <code>Function.prototype.apply</code> or <code>let n = 42;</code>.</p>
</blockquote>
<p>The source text is monospace in the original, while non-source language values are bold.</p>
<p>The sans-serif font is used for <a href="https://tc39.es/ecma262/multipage/ecmascript-data-types-and-values.html#sec-enum-specification-type" rel="nofollow noreferrer">abstract enumerators</a>; here the <a href="https://tc39.es/ecma262/multipage/abstract-operations.html#sec-toprimitive" rel="nofollow noreferrer">abstract ToPrimitive operation</a> has as its second parameter a choice of either String or Number to specify which sort of primitive it is converting to. These are literal values, not variables or in-language expressions, so are typeset distinctly. This appears in a few places throughout the specification; they could have defined separate operations for string and number, but in places need to refer to both together and have chosen this approach.</p>
<p>Other conventions are also given in-document where precise meaning is required, such as for the @@wellKnownSymbol case. These are bespoke for this language specification to represent recurring concepts and mark elements as carrying all of the formal properties of those concepts.</p>
<p>These are all fairly typical notational conventions, though which typeface is used for what purpose varies according to taste (or which points are expected to be more common). Until fairly recently the ECMAScript specifications existed only as for-print typeset documents and used typical formal typesetting techniques. The specification is not intended for beginners to read, so eschewing these conventions to make it (perhaps) easier for them to read is not likely to take priority over precision. Amiability to markdown is also not likely to have factored in. A new language’s specification that was <em>not</em> made for typesetting might not use all of these, and decide to strop more words instead, but this is all still consistent with current practice for formal descriptions of languages.</p>

CC BY-SA 4.0
2023-09-22T20:02:56.923Z
2023-09-26T19:18:07.987Z
2023-09-26T19:18:07.987Z
Michael Homer
CC BY-SA 4.0
2023-09-22T21:36:25.007Z
Formatting language specifications is an art -- too many concepts, not enough distinguishable fonts.
Barmar
CC BY-SA 4.0
2023-09-23T04:12:53.243Z
"*Until fairly recently*" - there are more versions released as a HTML document than not. And most of the bespoke formatting actually got introduced *after* the switch.
Bergi
CC BY-SA 4.0
2023-09-23T04:40:53.790Z
@Bergi Yeah, that's fair... the ES3 specification is regrettably no longer as recent as it seems. As far as I can tell most of these formatting conventions *are* from that era, though, and have been carried forward since. See e.g. the distinct usage of bold and fixed-width "true"s in the definition of Boolean literals going right back.
Michael Homer
CC BY-SA 4.0
2023-09-23T04:55:52.717Z
@MichaelHomer I think it was at least until ES5.1 that the spec was officially released as a PDF - remember https://es5.github.io (.com at the time)? But yeah, the basic formatting conventions can be found back then, I was thinking of the distinction between language (literal) values and mathematical value, or internal slot fonts.
Bergi
CC BY-SA 4.0
2023-09-23T07:40:34.893Z
@Bergi Somewhere I might still have a CD from ECMA with the spec on it in PDF form. Sending stuff out like that was quite an innovation, and it's fair to assume that current versions of the spec have inherited typesetting conventions that might not be used on a newly-written document.
Mark Morgan Lloyd
CC BY-SA 4.0
2023-09-23T07:41:47.353Z
@Barmar Hence the use of e.g. <prim> in many specifications of that era.
Mark Morgan Lloyd
CC BY-SA 4.0
2023-09-23T15:15:16.567Z
@MarkMorganLloyd The old PDFs can still be found at https://www.ecma-international.org/publications-and-standards/standards/ecma-262/. The only thing that's  lost (or: only [accessible via the wayback machine](https://web.archive.org/web/20161123164855/http://wiki.ecmascript.org/doku.php)) is the dokuwiki with the "harmony" proposals
Bergi
CC BY-SA 4.0
2023-09-23T15:31:33.800Z
No doubt. But the point I'm trying to make is that this was probably one of the earliest examples of somebody putting that much work into markup so represent linguistic elements in a standard.
Mark Morgan Lloyd
CC BY-SA 4.0
2023-09-25T15:08:29.367Z
@MarkMorganLloyd Kent Pitmann put lots of work into the Common Lisp standard back in the 90's. IIRC, he designed his own macro language that could generate HTML or TeX output. The HTML version can be found in the [Common Lisp Hyperspec](http://www.lispworks.com/documentation/HyperSpec/Front/index.htm)
Barmar
CC BY-SA 4.0
2023-09-26T17:44:59.097Z
‘Amiability to markdown is also not likely to have factored in.’ — this is arguably false, as the current spec is actually written in a dialect of Markdown called ecmarkup.
user3840170
# Why is the ECMAScript specification formatted the way it is?
Posted by: username_0 on 2023-09-22
The ECMAScript specification and its drafts are very accessible, but they're formatted a bit oddly -- case in point, the current version of [the ToBigInt abstract operation](https://tc39.es/ecma262/multipage/abstract-operations.html#sec-tobigint) uses three fonts:

[![A screenshot of the specification for the ToBigInt abstract operation. It uses three different fonts and multiple text colors.](https://i.sstatic.net/p6Csx.png)](https://i.sstatic.net/p6Csx.png)

* The base (serif) font
* A sans-serif font for the word "NUMBER"
* A monospace font for the BigInt literals **`1n`** and **`0n`**

Several other sections (though not this particular one) feature things such as @@wellKnownSymbol, [[InternalSlot]], and *%BuiltInClass%*.

While some of this formatting is helpful, such as to separate internal slots from properties visible to the JavaScript code, it's confusing especially to beginners, and the use of several fonts means it cannot be reproduced in e.g. markdown. Why did they choose to format it in this way?
**Tags:** javascript specification
> **Comments:**
> **username_1**: Why do you care about reproducing that typesetting in Markdown?  
> **username_0**: @Bergi Mostly when quoting it elsewhere, as many other sites (here, Reddit, Discord) use Markdown for formatting.  
> **username_2**: *"it's confusing especially to beginners"* - it's not meant for beginners. I would likewise strongly recommend against a beginner reading the Java Language Specification. Anything a beginner might want to know is explained elsewhere; the spec is intended mainly as a reference for implementors and language lawyers.  
> **username_3**: ECMAScript specs are full of WTFs. It only makes sense the formatting would follow this tradition too.  
> **username_4**: To be clear: the question is "what semantic information is conveyed by the font choice, or intended to be conveyed that way"? Or is it "why did the documentation writers think that this would be a good idea"? Or just what exactly?  
> **username_0**: @KarlKnechtel The latter.  
> **username_1**: @Bbrk24 Well the answer to that is "*because it **is** a good idea*", no? The spec is written for implementers who care about such details, it is not a tutorial for beginners.  
> **username_4**: It seems like the one answer you got so far inferred the former, so there is some amount of ambiguity here.  
> **username_5**: I don't see anything wrong with this question. Voting to reopen.  
---
## 1 answers
### Answer by username_6 on 2023-09-22. Score: 5
The ordinary bold text is used for ECMAScript values, while the monospace is for source text, as specified in Section

> [5.2.6 Value Notation](https://tc39.es/ecma262/multipage/notational-conventions.html#sec-value-notation)
>
> In this specification, ECMAScript language values are displayed in **bold**. Examples include **null**, **true**, or **"hello"**. These are distinguished from ECMAScript source text such as `Function.prototype.apply` or `let n = 42;`.

The source text is monospace in the original, while non-source language values are bold.

The sans-serif font is used for [abstract enumerators](https://tc39.es/ecma262/multipage/ecmascript-data-types-and-values.html#sec-enum-specification-type); here the [abstract ToPrimitive operation](https://tc39.es/ecma262/multipage/abstract-operations.html#sec-toprimitive) has as its second parameter a choice of either String or Number to specify which sort of primitive it is converting to. These are literal values, not variables or in-language expressions, so are typeset distinctly. This appears in a few places throughout the specification; they could have defined separate operations for string and number, but in places need to refer to both together and have chosen this approach.

Other conventions are also given in-document where precise meaning is required, such as for the @@wellKnownSymbol case. These are bespoke for this language specification to represent recurring concepts and mark elements as carrying all of the formal properties of those concepts.

These are all fairly typical notational conventions, though which typeface is used for what purpose varies according to taste (or which points are expected to be more common). Until fairly recently the ECMAScript specifications existed only as for-print typeset documents and used typical formal typesetting techniques. The specification is not intended for beginners to read, so eschewing these conventions to make it (perhaps) easier for them to read is not likely to take priority over precision. Amiability to markdown is also not likely to have factored in. A new language’s specification that was *not* made for typesetting might not use all of these, and decide to strop more words instead, but this is all still consistent with current practice for formal descriptions of languages.
> **Comments:**
> **username_7** (2023-09-22): Formatting language specifications is an art -- too many concepts, not enough distinguishable fonts.  
> **username_1** (2023-09-23): "*Until fairly recently*" - there are more versions released as a HTML document than not. And most of the bespoke formatting actually got introduced *after* the switch.  
> **username_6** (2023-09-23): @Bergi Yeah, that's fair... the ES3 specification is regrettably no longer as recent as it seems. As far as I can tell most of these formatting conventions *are* from that era, though, and have been carried forward since. See e.g. the distinct usage of bold and fixed-width "true"s in the definition of Boolean literals going right back.  
> **username_1** (2023-09-23): @MichaelHomer I think it was at least until ES5.1 that the spec was officially released as a PDF - remember https://es5.github.io (.com at the time)? But yeah, the basic formatting conventions can be found back then, I was thinking of the distinction between language (literal) values and mathematical value, or internal slot fonts.  
> **username_8** (2023-09-23): @Bergi Somewhere I might still have a CD from ECMA with the spec on it in PDF form. Sending stuff out like that was quite an innovation, and it's fair to assume that current versions of the spec have inherited typesetting conventions that might not be used on a newly-written document.  
> **username_8** (2023-09-23): @Barmar Hence the use of e.g. <prim> in many specifications of that era.  
> **username_1** (2023-09-23): @MarkMorganLloyd The old PDFs can still be found at https://www.ecma-international.org/publications-and-standards/standards/ecma-262/. The only thing that's  lost (or: only [accessible via the wayback machine](https://web.archive.org/web/20161123164855/http://wiki.ecmascript.org/doku.php)) is the dokuwiki with the "harmony" proposals  
> **username_8** (2023-09-23): No doubt. But the point I'm trying to make is that this was probably one of the earliest examples of somebody putting that much work into markup so represent linguistic elements in a standard.  
> **username_7** (2023-09-25): @MarkMorganLloyd Kent Pitmann put lots of work into the Common Lisp standard back in the 90's. IIRC, he designed his own macro language that could generate HTML or TeX output. The HTML version can be found in the [Common Lisp Hyperspec](http://www.lispworks.com/documentation/HyperSpec/Front/index.htm)  
> **username_9** (2023-09-26): ‘Amiability to markdown is also not likely to have factored in.’ — this is arguably false, as the current spec is actually written in a dialect of Markdown called ecmarkup.  
---
