From cb5a2e27ed024b33e169c9344a5ddcb829ecc6ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aki=20=F0=9F=8C=B9?= Date: Thu, 13 Jun 2024 13:13:09 -0700 Subject: [PATCH] Markup: Add print.css; update graphics; add PUBLISHING document --- PUBLISHING.md | 20 +++++ img/ecma-header.svg | 1 + img/ecma-logo.svg | 121 +------------------------------ img/figure-1.svg | 2 +- img/figure-2.svg | 2 +- img/module-graph-cycle-async.svg | 70 +----------------- img/module-graph-cycle.svg | 64 +--------------- img/module-graph-missing.svg | 49 +------------ img/module-graph-simple.svg | 57 +-------------- img/print-front-cover.svg | 10 +++ img/print-inside-cover.svg | 59 +++++++++++++++ package.json | 4 +- print.css | 100 +++++++++++++++++++++++++ spec.html | 32 +------- 14 files changed, 203 insertions(+), 388 deletions(-) create mode 100644 PUBLISHING.md create mode 100644 img/ecma-header.svg create mode 100644 img/print-front-cover.svg create mode 100644 img/print-inside-cover.svg create mode 100644 print.css diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000000..942e5b0e03 --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,20 @@ +# Publishing the annual PDF + +First, make sure you've provided appropriate front matter. `title`, `shortname`, `version`, and `date` are **mandatory**. If generating a final annual edition, date should reflect the date of the Ecma GA which will ratify the Standard. For example: + +``` +title: ECMAScript® 2024 Language Specification +shortname: ECMA-262 +version: 15th Edition +date: 2024-06-25 +``` + +Use the package script `build-for-pdf`. Importantly, you want to make sure your image directory and print.css file wind up in the same output directory as your markup, i.e. your `ecmarkup` command should include the options `--assets external`, `--assets-dir out`, and `--old-toc`. + +Then, run `prince` to generate your PDF. + +```shell +prince --script ./node_modules/ecmarkup/js/print.js out/index.html -o path/to/output.pdf +``` + +Spend 5-10 minutes double-checking the PDF for egregious layout issues. That means quickly skimming all 800+ pages looking for whitespace or content split in a confusing manner. Tinker with `print.css` only as needed. Compare cover & table of contents to previous years. diff --git a/img/ecma-header.svg b/img/ecma-header.svg new file mode 100644 index 0000000000..5eaffa9d75 --- /dev/null +++ b/img/ecma-header.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/img/ecma-logo.svg b/img/ecma-logo.svg index 9fee7c8f3b..32020be0a5 100644 --- a/img/ecma-logo.svg +++ b/img/ecma-logo.svg @@ -1,120 +1 @@ - -image/svg+xml \ No newline at end of file + \ No newline at end of file diff --git a/img/figure-1.svg b/img/figure-1.svg index abb4252cb0..0605417e46 100644 --- a/img/figure-1.svg +++ b/img/figure-1.svg @@ -15,7 +15,7 @@ marker-end: url(#arrowhead); } path.d { stroke-dasharray: 2,2; } - text { font-family: Helvetica, Arial, Liberation Sans, sans-serif; } + text { font-family: Arial, Liberation Sans, sans-serif; } text.pn { font-family: "Courier New", monospace; } text.on { font-weight: bold; } text.ons { font-weight: bold; font-size: 60%; } diff --git a/img/figure-2.svg b/img/figure-2.svg index ef20a19c0f..ddca4d2539 100644 --- a/img/figure-2.svg +++ b/img/figure-2.svg @@ -68,7 +68,7 @@ stroke-dasharray: 6, 6; } - text { font-family: Helvetica, Arial, Liberation Sans, sans-serif; } + text { font-family: Arial, Liberation Sans, sans-serif; } text { font-size: 14px; } diff --git a/img/module-graph-cycle-async.svg b/img/module-graph-cycle-async.svg index d9da548aa3..76bd0290fd 100644 --- a/img/module-graph-cycle-async.svg +++ b/img/module-graph-cycle-async.svg @@ -1,69 +1 @@ - - - - - - - - - - -A - - -B - - -C - - -D - - -E - - - - - - - - - - +ABCDE diff --git a/img/module-graph-cycle.svg b/img/module-graph-cycle.svg index ecf7d58520..12628e8ed6 100644 --- a/img/module-graph-cycle.svg +++ b/img/module-graph-cycle.svg @@ -1,63 +1 @@ - - - - - - - - - - -A - - -B - - -C - - - - - - - - - +ABC diff --git a/img/module-graph-missing.svg b/img/module-graph-missing.svg index e37d9f7614..a23f0eeb25 100644 --- a/img/module-graph-missing.svg +++ b/img/module-graph-missing.svg @@ -1,48 +1 @@ - - - - - - - - - - -A - - -??? - - - - - +A??? diff --git a/img/module-graph-simple.svg b/img/module-graph-simple.svg index 055ad7a660..527bcd8307 100644 --- a/img/module-graph-simple.svg +++ b/img/module-graph-simple.svg @@ -1,56 +1 @@ - - - - - - - - - - -A - - -B - - -C - - - - - - +ABC diff --git a/img/print-front-cover.svg b/img/print-front-cover.svg new file mode 100644 index 0000000000..aa0ae35721 --- /dev/null +++ b/img/print-front-cover.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/img/print-inside-cover.svg b/img/print-inside-cover.svg new file mode 100644 index 0000000000..c0f6f02de9 --- /dev/null +++ b/img/print-inside-cover.svg @@ -0,0 +1,59 @@ + + + + + + + COPYRIGHT PROTECTED DOCUMENT + + + Ecma International + Rue du Rhone 114 CH-1204 Geneva + Tel: +41 22 849 6000 + Fax: +41 22 849 6001 + Web: + + + https://www.ecma-international.org + + + + + © Ecma International + + + + + + + + is the registered trademark of Ecma International + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/package.json b/package.json index 013ffb2639..9422e3d88e 100644 --- a/package.json +++ b/package.json @@ -9,8 +9,8 @@ "prebuild-only": "npm run clean && mkdir out && cp -R img out", "build-only": "ecmarkup --verbose spec.html --multipage out", "build": "npm run build-head", - "build-for-pdf": "ecmarkup --verbose spec.html --old-toc --assets external out/index.html", - "pdf": "npm run build-for-pdf && pagedjs-cli --page-size a4 out/index.html -o out/index.pdf", + "build-for-pdf": "npm run prebuild-only && cp print.css out && ecmarkup --verbose spec.html out/index.html --assets external --assets-dir out --old-toc --lint-spec --strict", + "pdf": "npm run build-for-pdf && prince --script ./node_modules/ecmarkup/js/print.js out/index.html -o out/ECMA-262.pdf", "prebuild-snapshot": "npm run clean", "build-snapshot": "npm run build-head && node scripts/insert_snapshot_warning.js", "clean": "rm -rf out", diff --git a/print.css b/print.css new file mode 100644 index 0000000000..2f39f6216a --- /dev/null +++ b/print.css @@ -0,0 +1,100 @@ +/** +* ECMA-262-specific hacks. Shouldn't require a ton of maintenance; audit if +* visual inspection results in unexpected page breaks. +*/ +/* 2.2 Examples of legacy/normative-optional are small enough to be aggressive against breaks */ +#sec-conformance [example], + +/* 8.3.3 avoid breaking in small alg lists */ +#sec-static-semantics-containsundefinedcontinuetarget li, + +/* 16.2.1.5.4 many tables */ +#table-module-graph-cycle-async-fields-1 table, +#table-module-graph-cycle-async-fields-9 table { + break-inside: avoid-page; +} + +/* 12.10.1 long note can break wherever it wants */ +#sec-rules-of-automatic-semicolon-insertion > emu-note { + break-before: initial; + break-inside: initial; +} + +/* 12.10.2, 12.10.3, 12.10.3.2 Sections start with an not inside a

*/ +#sec-examples-of-automatic-semicolon-insertion > em, +#sec-interesting-cases-of-automatic-semicolon-insertion > em, +#sec-asi-cases-with-no-lineterminator-here > em { + display: block; + margin-top: 1.25ex; +} + +/* 15.1.2 bad spacing between intro and first emu-grammar */ +#sec-static-semantics-containsexpression > emu-grammar:first-of-type { + margin-top: 2ex; +} + +/* 15.3 A very long term combined with inline-block, nowrap, and justified text resulting in weird punctuation */ +#sec-arrow-function-definitions > p > emu-grammar { + text-align: left; +} + +/* 16.2.1.5.4 squish margins on graphics so table 46 fits on one page */ +#sec-example-cyclic-module-record-graphs figure:has(> img), +#sec-example-cyclic-module-record-graphs figure > img { + margin: 0; +} +#sec-example-cyclic-module-record-graphs figure:has(> img) > figcaption { + margin-bottom: 1ex; +} +#sec-example-cyclic-module-record-graphs emu-figure:has(> figure > img) + p { + margin-top: 1ex; +} + +/* 16.2.1.5.4 table 51 & 54 are too narrow for caption */ +#table-module-graph-cycle-async-fields-6 table { + width: 110mm; +} +#table-module-graph-cycle-async-fields-9 table { + width: 135mm; +} + +/* 20.1.3.7 legacy title */ +#sec-object\.prototype\.__proto__ > .attributes-tag { + break-before: avoid-page; + break-after: avoid-page; +} + +/* 21.4.1.22 Table 61 middle column is too narrow */ +#table-time-zone-identifier-record-fields > figure > table th:nth-of-type(2) { + width: 15%; +} + +/* 21.4.4.41.2 These tables are way too narrow for their captions */ +#sec-todatestring-day-names table, +#sec-todatestring-month-names table { + width: 100mm; +} + +/* 27.2.6 squeeze to make more room for figure-2.svg */ +#table-internal-slots-of-promise-instances > figure { + margin-bottom: 0; +} + +/* 27.3 fit generator objects relationships diagram */ +#sec-generatorfunction-objects, +#sec-generatorfunction-objects h1 { + margin-top: 1.5ex; +} + +/* 27.3 `figure-2.svg` is just a tiny bit too big to fit on the page, results in weird white space */ +#figure-2 figure { + margin: 1ex 0; +} +#figure-2 > figure > img { + width: 97%; +} + +/* 29.11 extremely long note */ +#sec-shared-memory-guidelines > emu-note { + break-inside: auto; +} diff --git a/spec.html b/spec.html index 4243466322..90453e4e45 100644 --- a/spec.html +++ b/spec.html @@ -2,31 +2,7 @@ - + 

   title: ECMAScript® 2025 Language Specification
   shortname: ECMA-262
@@ -26945,7 +26921,7 @@ 
Example Cyclic Module Record Graphs

           
First consider the following simple module graph:

 
           
-            A module graph in which module A depends on module B, and module B depends on module C
+            A module graph in which module A depends on module B, and module B depends on module C
           
 
           
Let's first assume that there are no error conditions. When a host first calls _A_.LoadRequestedModules(), this will complete successfully by assumption, and recursively load the dependencies of _B_ and _C_ as well (respectively, _C_ and none), and then set _A_.[[Status]] = _B_.[[Status]] = _C_.[[Status]] = ~unlinked~. Then, when the host calls _A_.Link(), it will complete successfully (again by assumption) such that _A_.[[Status]] = _B_.[[Status]] = _C_.[[Status]] = linked. These preparatory steps can be performed at any time. Later, when the host is ready to incur any possible side effects of the modules, it can call _A_.Evaluate(), which will complete successfully, returning a Promise resolving to *undefined* (again by assumption), recursively having evaluated first _C_ and then _B_. Each module's [[Status]] at this point will be ~evaluated~.

@@ -26957,7 +26933,7 @@ 
Example Cyclic Module Record Graphs

           
Now consider a different type of error condition:

 
           
-            A module graph in which module A depends on a missing (unresolvable) module, represented by ???
+            A module graph in which module A depends on a missing (unresolvable) module, represented by ???
           
 
           
In this scenario, module _A_ declares a dependency on some other module, but no Module Record exists for that module, i.e. HostLoadImportedModule calls FinishLoadingImportedModule with an exception when asked for it. This could occur for a variety of reasons, such as the corresponding resource not existing, or the resource existing but ParseModule returning some errors when trying to parse the resulting source text. Hosts can choose to expose the cause of failure via the completion they pass to FinishLoadingImportedModule. In any case, this exception causes a loading failure, which results in _A_'s [[Status]] remaining ~new~.

@@ -51421,7 +51397,7 @@ 
Additions and Changes That Introduce Incompatibilities with Prior Editions
   
Colophon

-  
This specification is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMAScript specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps. PDF renderings of this specification are produced by printing the HTML rendering to a PDF.

+  
This specification is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMAScript specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdownfor authoring algorithm steps. PDF renderings of this specification are produced using a print stylesheet which takes advantage of the CSS Paged Media specification and is converted using PrinceXML.

   
Prior editions of this specification were authored using Word—the Ecmarkup source text that formed the basis of this edition was produced by converting the ECMAScript 2015 Word document to Ecmarkup using an automated conversion tool.