Restore superscripts that are stripped by yaml parser in print js (#648)

* Restore superscripts that are stripped by yaml parser, orphan and widow tweaks, move medatadata box styles from specs to ecmarkup

* Add prince documentation links, update PUBLISHING.md

Author: gesa

PUBLISHING.md

@@ -11,7 +11,7 @@ status: proposal
 stage: 3
 ```
 
-- If using the alternative copyright for a standard publication, `location` is also mandatory. For example:
+- You can also specify various boilerplate content (see the boilerplate/ directory)  For example:
 
 ```yaml
 title: ECMAScript® Language Specification
@@ -34,6 +34,8 @@ boilerplate:
 location: https://262.ecma-international.org/16.0/
 ```
 
+## Build and print
+
 To generate markup for use in PDF conversion, make sure to include the options `--assets`, `--assets-dir`, and `--printable`. If you have images and styles to include, make sure to move them into your assets directory before running `ecmarkup`. For example:
 
 ```shell
@@ -49,4 +51,4 @@ cd path/to/spec
 prince-books --script ./node_modules/ecmarkup/js/print.js out/index.html -o path/to/output.pdf
 ```
 
-This has been extensively tested with Prince 15. Earlier and later editions not guaranteed.
+This has been extensively tested with [Prince Books](https://www.princexml.com/books/), built off of Prince 15. Earlier and later editions not guaranteed. CSS rule-specific documentation available in css/print.css.

css/elements.css

@@ -289,6 +289,23 @@ body.oldtoc {
   margin: 0 auto;
 }
 
+#metadata-block {
+  margin: 4em 0;
+  padding: 10px;
+  border: 1px solid #ee8421;
+}
+
+#metadata-block h1 {
+  font-size: 1.5em;
+  margin-top: 0;
+}
+
+#metadata-block > ul {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+}
+
 span[aria-hidden='true'] {
   font-size: 0;
   white-space: pre;
@@ -1627,4 +1644,5 @@ emu-normative-optional,
 
 #ecma-logo {
   background: var(--figure-background);
+  width: 500px;
 }

css/print.css

@@ -69,6 +69,7 @@
 
 :root {
   --page-number-style: decimal;
+  -prince-change-line-breaks-for-pagination: yes; /* see https://www.princexml.com/doc/prince-for-books/#pagination-fine-tuning */
 }
 
 @page {
@@ -77,16 +78,16 @@
   margin-bottom: 20mm;
   margin-inside: 19mm;
   margin-outside: 13mm;
-  -prince-page-fill: prefer-fill;
+  -prince-page-fill: prefer-balance; /* see https://www.princexml.com/doc/prince-for-books/#the-property--prince-page-fill */
 
-  /* Uncomment when producing WIP versions of final standards */
+  /* Uncomment when producing WIP versions of final standards, see https://www.princexml.com/doc/paged/#page-regions */
   /*
   @prince-overlay {
     color: rgba(0,0,0,0.15);
-    content: "WORK IN PROGRESS";
+    content: "DRAFT";
     font-family: Arial;
     font-weight: bolder;
-    font-size: 100pt;
+    font-size: 200pt;
     transform: rotate(-60deg);
   }
   */
@@ -196,7 +197,7 @@ body {
   line-height: 1.15;
 }
 
-h1, h2, h3, h4, h5, h6 { -prince-bookmark-level: none }
+h1, h2, h3, h4, h5, h6 { -prince-bookmark-level: none } /* see https://www.princexml.com/doc/prince-output/#pdf-bookmarks */
 
 .copyright-notice + h1.title {
   break-before: recto;
@@ -216,15 +217,24 @@ p {
   text-wrap: pretty;
   overflow-wrap: break-word;
   hyphens: auto;
-  orphans: 2;
-  widows: 2;
+  orphans: 2, -prince-prefer 3; /* see https://www.princexml.com/doc/prince-for-books/#pagination-goals */
+  widows: 2, -prince-prefer 3;
 }
 
 h1 {
   text-wrap: balance;
   line-height: 1.4;
 }
 
+pre:has(> code) {
+  margin: 0;
+}
+
+p + pre:has(+ p) {
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
 emu-alg {
   display: block; /* Can't render block elements inside inline elements. */
 }
@@ -263,6 +273,10 @@ emu-alg ol li:last-child {
   break-after: initial; /* it's okay to break after the last item in a list, even if it's also the first item in the list */
 }
 
+emu-normative-optional {
+  break-inside: avoid;
+}
+
 emu-normative-optional emu-clause[id] {
   margin-top: 0;
 }
@@ -281,6 +295,10 @@ emu-note .note {
   min-width: 4.5em;
 }
 
+emu-note table td {
+  background-color: white;
+}
+
 emu-note p,
 emu-table td p {
   text-align: left;
@@ -309,7 +327,6 @@ emu-intro, emu-clause, emu-annex {
 }
 
 emu-clause p:first-of-type {
-  margin-bottom: 0;
   orphans: 3;
 }
 
@@ -429,7 +446,7 @@ caption, table > figcaption {
 }
 
 caption {
-  -prince-caption-page: first;
+  -prince-caption-page: first; /* see https://www.princexml.com/doc/css-props/#prop-prince-caption-page */
 }
 
 /* do not break inside of small tables */
@@ -470,6 +487,11 @@ emu-figure img {
   height: auto;
 }
 
+.attributes-tag {
+  break-before: avoid-page;
+  break-after: avoid-page;
+}
+
 #spec-container {
   max-width: initial;
 }
@@ -565,8 +587,8 @@ emu-annex > h1 .secnum {
   border: 1px solid black;
   padding: 1em;
   page: copyright;
-  page-break-before: always;
-  page-break-after: always;
+  break-before: page;
+  break-after: page;
 }
 
 .secnum {

js/print.js

@@ -12,6 +12,11 @@
 
 const shortname = document.querySelector('h1.shortname');
 const version = document.querySelector('h1.version');
+const title = document.querySelector('h1.title');
+
+shortname.innerHTML = restoreSuperScripts(shortname.innerHTML);
+version.innerHTML = restoreSuperScripts(version.innerHTML);
+title.innerHTML = restoreSuperScripts(title.innerHTML);
 
 rearrangeTables();
 
@@ -22,6 +27,20 @@ PDF.title = document.title;
 PDF.author = 'Ecma International';
 PDF.subject = shortname.innerHTML + (version ? ', ' + version.innerHTML : '');
 
+function restoreSuperScripts(string) {
+  if (!string) return false;
+
+  return string
+    .replace(/(\d)st/, '$1<sup>st</sup>')
+    .replace(/(\d)nd/, '$1<sup>nd</sup>')
+    .replace(/(\d)rd/, '$1<sup>rd</sup>')
+    .replace(/(\d)th/, '$1<sup>th</sup>')
+    .replace('&reg;', '<sup>&reg;</sup>')
+    .replace('®', '<sup>®</sup>')
+    .replace('&trade;', '<sup>&trade;</sup>')
+    .replace('™', '<sup>™</sup>');
+}
+
 /**
  * Sets up table captions and figcaptions for tables, which provides for
  * continuation table captions.

test/baselines/generated-reference/assets-inline.html

@@ -1906,6 +1906,23 @@
   margin: 0 auto;
 }
 
+#metadata-block {
+  margin: 4em 0;
+  padding: 10px;
+  border: 1px solid #ee8421;
+}
+
+#metadata-block h1 {
+  font-size: 1.5em;
+  margin-top: 0;
+}
+
+#metadata-block > ul {
+  list-style-type: none;
+  margin: 0;
+  padding: 0;
+}
+
 span[aria-hidden='true'] {
   font-size: 0;
   white-space: pre;
@@ -3244,6 +3261,7 @@
 
 #ecma-logo {
   background: var(--figure-background);
+  width: 500px;
 }
 </style><style>@media print {
 @font-face {
@@ -3317,6 +3335,7 @@
 
 :root {
   --page-number-style: decimal;
+  -prince-change-line-breaks-for-pagination: yes; /* see https://www.princexml.com/doc/prince-for-books/#pagination-fine-tuning */
 }
 
 @page {
@@ -3325,16 +3344,16 @@
   margin-bottom: 20mm;
   margin-inside: 19mm;
   margin-outside: 13mm;
-  -prince-page-fill: prefer-fill;
+  -prince-page-fill: prefer-balance; /* see https://www.princexml.com/doc/prince-for-books/#the-property--prince-page-fill */
 
-  /* Uncomment when producing WIP versions of final standards */
+  /* Uncomment when producing WIP versions of final standards, see https://www.princexml.com/doc/paged/#page-regions */
   /*
   @prince-overlay {
     color: rgba(0,0,0,0.15);
-    content: "WORK IN PROGRESS";
+    content: "DRAFT";
     font-family: Arial;
     font-weight: bolder;
-    font-size: 100pt;
+    font-size: 200pt;
     transform: rotate(-60deg);
   }
   */
@@ -3444,7 +3463,7 @@
   line-height: 1.15;
 }
 
-h1, h2, h3, h4, h5, h6 { -prince-bookmark-level: none }
+h1, h2, h3, h4, h5, h6 { -prince-bookmark-level: none } /* see https://www.princexml.com/doc/prince-output/#pdf-bookmarks */
 
 .copyright-notice + h1.title {
   break-before: recto;
@@ -3464,15 +3483,24 @@
   text-wrap: pretty;
   overflow-wrap: break-word;
   hyphens: auto;
-  orphans: 2;
-  widows: 2;
+  orphans: 2, -prince-prefer 3; /* see https://www.princexml.com/doc/prince-for-books/#pagination-goals */
+  widows: 2, -prince-prefer 3;
 }
 
 h1 {
   text-wrap: balance;
   line-height: 1.4;
 }
 
+pre:has(> code) {
+  margin: 0;
+}
+
+p + pre:has(+ p) {
+  padding-top: 0;
+  padding-bottom: 0;
+}
+
 emu-alg {
   display: block; /* Can't render block elements inside inline elements. */
 }
@@ -3511,6 +3539,10 @@
   break-after: initial; /* it's okay to break after the last item in a list, even if it's also the first item in the list */
 }
 
+emu-normative-optional {
+  break-inside: avoid;
+}
+
 emu-normative-optional emu-clause[id] {
   margin-top: 0;
 }
@@ -3529,6 +3561,10 @@
   min-width: 4.5em;
 }
 
+emu-note table td {
+  background-color: white;
+}
+
 emu-note p,
 emu-table td p {
   text-align: left;
@@ -3557,7 +3593,6 @@
 }
 
 emu-clause p:first-of-type {
-  margin-bottom: 0;
   orphans: 3;
 }
 
@@ -3677,7 +3712,7 @@
 }
 
 caption {
-  -prince-caption-page: first;
+  -prince-caption-page: first; /* see https://www.princexml.com/doc/css-props/#prop-prince-caption-page */
 }
 
 /* do not break inside of small tables */
@@ -3718,6 +3753,11 @@
   height: auto;
 }
 
+.attributes-tag {
+  break-before: avoid-page;
+  break-after: avoid-page;
+}
+
 #spec-container {
   max-width: initial;
 }
@@ -3813,8 +3853,8 @@
   border: 1px solid black;
   padding: 1em;
   page: copyright;
-  page-break-before: always;
-  page-break-after: always;
+  break-before: page;
+  break-after: page;
 }
 
 .secnum {