3
$\begingroup$

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 uses three fonts:

A screenshot of the specification for the ToBigInt abstract operation. It uses three different fonts and multiple text colors.

  • 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?

$\endgroup$
9
  • 3
    $\begingroup$ Why do you care about reproducing that typesetting in Markdown? $\endgroup$
    – Bergi
    Sep 23 at 4:08
  • 1
    $\begingroup$ @Bergi Mostly when quoting it elsewhere, as many other sites (here, Reddit, Discord) use Markdown for formatting. $\endgroup$
    – Bbrk24
    Sep 23 at 5:50
  • 6
    $\begingroup$ "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. $\endgroup$
    – kaya3
    Sep 23 at 9:04
  • $\begingroup$ ECMAScript specs are full of WTFs. It only makes sense the formatting would follow this tradition too. $\endgroup$
    – Eric Duminil
    Sep 23 at 16:11
  • $\begingroup$ 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? $\endgroup$
    – Karl Knechtel
    Sep 30 at 10:13

1 Answer 1

Reset to default
5
$\begingroup$

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

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; here the abstract ToPrimitive operation 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.

$\endgroup$
10
  • 2
    $\begingroup$ Formatting language specifications is an art -- too many concepts, not enough distinguishable fonts. $\endgroup$
    – Barmar
    Sep 22 at 21:36
  • $\begingroup$ "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. $\endgroup$
    – Bergi
    Sep 23 at 4:12
  • $\begingroup$ @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. $\endgroup$
    – Michael Homer ♦
    Sep 23 at 4:40
  • $\begingroup$ @MichaelHomer I think it was at least until ES5.1 that the spec was officially released as a PDF - remember 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. $\endgroup$
    – Bergi
    Sep 23 at 4:55
  • $\begingroup$ @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. $\endgroup$
    – Mark Morgan Lloyd
    Sep 23 at 7:40

Not the answer you're looking for? Browse other questions tagged .