Update ecmarkup output to align more closely with ecma guidelines

css/print.css

@@ -427,7 +427,7 @@ emu-table th {
 
 caption, table > figcaption {
   caption-side: top;
-  color: #555555;
+  color: #000;
   font-weight: bold;
   margin-bottom: 1rem;
   text-align: center;
@@ -442,6 +442,7 @@ table:not(:has(tr:nth-of-type(5))) {
   break-inside: avoid-page;
 }
 
+/* This inheritance looks weird—it's due to how Prince manages continuity in tables across pages */
 table > figcaption {
   display: table-caption;
   -prince-caption-page: following;
@@ -658,3 +659,23 @@ h1.version {
 p.ECMAaddress {
   margin: 0;
 }
+
+#sec-terms-and-definitions dfn {
+  font-style: normal;
+}
+
+#sec-terms-and-definitions h1 .secnum {
+  display: block;
+}
+
+#sec-terms-and-definitions > h1 > .secnum {
+  display: inline;
+}
+
+#sec-terms-and-definitions h1 + p {
+  margin-top: 0;
+}
+
+p.adoption-info {
+  float: bottom;
+}

js/print.js

@@ -27,6 +27,15 @@ PDF.title = document.title;
 PDF.author = 'Ecma International';
 PDF.subject = shortname.innerHTML + (version ? ', ' + version.innerHTML : '');
 
+/**
+ * Terms and definitions section should not have every term listed in the table of contents.
+ * */
+const terms = document.querySelector('#toc a[href="#sec-terms-and-definitions"]');
+
+if (terms) {
+  (terms.parentElement.querySelector('ol.toc') || document.createElement('i')).remove();
+}
+
 function restoreSuperScripts(string) {
   if (!string) return false;
 

spec/index.html

@@ -69,12 +69,13 @@ <h1>Options</h1>
       <tr><td></td><td>`status`</td><td>Document status. Can be "proposal", "draft", or "standard". Defaults to "proposal".</td></tr>
       <tr><td></td><td>`stage`</td><td><a href="https://tc39.es/process-document/">TC39 proposal stage</a>. If present and `status` is "proposal", `version` defaults to "Stage <var>stage</var> Draft".</td></tr>
       <tr><td></td><td>`version`</td><td>Document version, for example "6&lt;sup>th&lt;/sup> Edition" (which renders like "6<sup>th</sup> Edition") or "Draft 1".</td></tr>
-      <tr><td></td><td>`date`</td><td>Timestamp of document rendering, used for various pieces of boilerplate. Defaults to the value of <a href="https://reproducible-builds.org/docs/source-date-epoch/">the `SOURCE_DATE_EPOCH` environment variable</a> (as a number of second since the POSIX epoch) if it exists, otherwise to the current date and time.</td></tr>
+      <tr><td></td><td>`date`</td><td>Timestamp of document rendering, used for various pieces of boilerplate. Defaults to the value of <a href="https://reproducible-builds.org/docs/source-date-epoch/">the `SOURCE_DATE_EPOCH` environment variable</a> (as a number of second since the POSIX epoch) if it exists, otherwise to the current date and time. Required for documents with "standard" status, should reflect adoption date.</td></tr>
       <tr><td></td><td>`shortname`</td><td>Document shortname, for example "ECMA-262". If present and `status` is "draft", `version` defaults to "Draft <var>shortname</var>".</td></tr>
       <tr><td></td><td>`description`</td><td>Brief description to be used for link previews in social media and the like.</td></tr>
       <tr><td></td><td>`location`</td><td>URL of this document. Used in conjunction with the biblio file to support inbound references from other documents.</td></tr>
       <tr><td></td><td>`copyright`</td><td>Emit copyright and software license information. Boolean, default true.</td></tr>
       <tr><td></td><td>`contributors`</td><td>Contributors to this specification, i.e. those who own the copyright. If your proposal includes text from any Ecma specification, this should include "Ecma International".</td></tr>
+      <tr><td></td><td>`committee`</td><td>Ecma Technical Committee number. Required for documents with "standard" status, expects e.g. "39". Appends adoption information to &lt;emu-intro> element.</td></tr>
       <tr><td>`--no-toc`</td><td>`toc`</td><td>Emit table of contents. Boolean, default true.</td></tr>
       <tr><td>`--printable`</td><td>`printable`</td><td>Make the output suitable for printing. Boolean, default false.</td></tr>
       <tr><td>`--load-biblio`</td><td>`extraBiblios`</td><td>Extra biblio.json file(s) to load. This should contain either an object as exported by `--write-biblio` or an array of such objects.</td></tr>

src/Spec.ts

@@ -594,9 +594,26 @@ export default class Spec {
 
     if (this.opts.printable) {
       this.log('Building covers and applying other print tweaks...');
+
+      const intro = this.doc.querySelector('emu-intro');
+
+      if (this.opts.status === 'standard') {
+        if (this.opts.committee) {
+          const adoptionInfo = this.doc.createElement('p');
+
+          adoptionInfo.classList.add('adoption-info');
+          adoptionInfo.innerHTML = `This Ecma Standard was developed by Technical Committee ${this.opts.committee} and was adopted by the General Assembly of ${Intl.DateTimeFormat('en-GB-oxendict', { month: 'long', year: 'numeric' }).format(this.opts.date)}.`;
+          intro!.appendChild(adoptionInfo);
+        } else {
+          throw new Error(
+            '"standard" status requires a technical committee be defined in the "committee" field of the metadata.',
+          );
+        }
+      }
+
       const metadataEle = this.doc.querySelector('#metadata-block');
       if (metadataEle) {
-        this.doc.querySelector('emu-intro')!.appendChild(metadataEle);
+        intro!.appendChild(metadataEle);
       }
 
       // front cover
@@ -629,7 +646,8 @@ export default class Spec {
       this.log('Building table of contents...');
 
       if (this.opts.printable) {
-        new Toc(this).build(2);
+        // Ecma guidance directs three levels of clause in ToC
+        new Toc(this).build(3);
       } else {
         ({ js: tocJs, eles: commonEles } = makeMenu(this));
       }
@@ -1194,11 +1212,7 @@ ${await utils.readFile(path.join(__dirname, '../js/multipage.js'))}
       script.setAttribute('defer', '');
       this.doc.head.appendChild(script);
 
-      this.addStyle(
-        this.doc.head,
-        path.relative(outDir, printStyleLocationOnDisk),
-        this.opts.printable ? undefined : 'print',
-      );
+      this.addStyle(this.doc.head, path.relative(outDir, printStyleLocationOnDisk), 'print');
       this.addStyle(this.doc.head, path.relative(outDir, styleLocationOnDisk));
     } else {
       // i.e. assets.type === 'inline'
@@ -1494,15 +1508,14 @@ ${this.opts.multipage ? `<li><span>Navigate to/from multipage</span><code>m</cod
       }
     }
 
-    // no title boilerplate generated if title not specified
-    if (!title) return;
-
     // title
     if (title && !this._updateBySelector('title', title)) {
       const titleElem = this.doc.createElement('title');
       titleElem.innerHTML = utils.textContentFromHTML(this.doc, title);
       this.doc.head.appendChild(titleElem);
+    }
 
+    if (title && !this._updateBySelector('h1.title', title)) {
       const h1 = this.doc.createElement('h1');
       h1.setAttribute('class', 'title');
       h1.innerHTML = title;
@@ -1615,7 +1628,11 @@ ${this.opts.multipage ? `<li><span>Navigate to/from multipage</span><code>m</cod
       }
     }
 
-    let copyright = getBoilerplate(copyrightFile || `${this.opts.status}-copyright`);
+    // Ecma documents should exclusively have either the standard copyright or the alternative copyright.
+    // Proposals are not Ecma documents.
+    let copyright = getBoilerplate(
+      copyrightFile || `${this.opts.status !== 'proposal' ? 'standard' : 'proposal'}-copyright`,
+    );
     const copyrightElement = this.doc.createElement('div');
 
     copyrightElement.classList.add('copyright-notice');

src/ecmarkup.ts

@@ -49,6 +49,7 @@ export interface Options {
   boilerplate?: Boilerplate;
   log?: (msg: string) => void;
   warn?: (err: EcmarkupError) => void;
+  committee?: number;
 }
 
 export async function build(

src/lint/collect-spelling-diagnostics.ts

@@ -73,7 +73,7 @@ const matchers = [
     // https://en.wikipedia.org/wiki/American_and_British_English_spelling_differences#-our%2C_-or
     pattern:
       /\b(?:[Bb]ehaviors?|[Ff]lavors?|[Hh]arbors?|[Hh]onors?|[Hh]umors?|[Ll]abors?|[Nn]eighbors?|[Rr]umors?|[Ss]plendors?)\b/gu,
-    message: 'ECMA-262 uses Oxford spelling ("behaviour", etc.)',
+    message: 'Ecma uses Oxford spelling ("behaviour", etc.)',
   },
   {
     pattern: /\b[Ii]ndexes\b/gu,

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

@@ -3679,7 +3679,7 @@
 
 caption, table > figcaption {
   caption-side: top;
-  color: #555555;
+  color: #000;
   font-weight: bold;
   margin-bottom: 1rem;
   text-align: center;
@@ -3694,6 +3694,7 @@
   break-inside: avoid-page;
 }
 
+/* This inheritance looks weird—it's due to how Prince manages continuity in tables across pages */
 table > figcaption {
   display: table-caption;
   -prince-caption-page: following;
@@ -3911,6 +3912,26 @@
   margin: 0;
 }
 
+#sec-terms-and-definitions dfn {
+  font-style: normal;
+}
+
+#sec-terms-and-definitions h1 .secnum {
+  display: block;
+}
+
+#sec-terms-and-definitions > h1 > .secnum {
+  display: inline;
+}
+
+#sec-terms-and-definitions h1 + p {
+  margin-top: 0;
+}
+
+p.adoption-info {
+  float: bottom;
+}
+
 }</style><style>
     @media print {
       @page :left {

test/baselines/generated-reference/boilerplate-address.html

@@ -21,15 +21,29 @@ <h1>Copyright &amp; Software License</h1>
 <p class="ECMAaddress">Web: <a href="http://www.tet-corporation.com/">http://www.tet-corporation.com/</a></p>
 
         <div class="copyright-notice" id="copyright-notice"><h2>Copyright Notice</h2>
+<p>COPYRIGHT NOTICE</p>
+
 <p>© 2018 Ecma International</p>
 
-<p>This draft document may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as needed for the purpose of developing any document or deliverable produced by Ecma International.</p>
+<p>By obtaining and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.</p>
+
+<p>This document may be copied, published and distributed to others, and certain derivative works of it may be prepared, copied, published, and distributed, in whole or in part, provided that the above copyright notice and this Copyright License and Disclaimer are included on all such copies and derivative works. The only derivative works that are permissible under this Copyright License and Disclaimer are:</p>
+
+<p>(i) works which incorporate all or portion of this document for the purpose of providing commentary or explanation (such as an annotated version of the document),</p>
+
+<p>(ii) works which incorporate all or portion of this document for the purpose of incorporating features that provide accessibility,</p>
+
+<p>(iii) translations of this document into languages other than English and into different formats and</p>
+
+<p>(iv) works by making use of this specification in standard conformant products by implementing (e.g. by copy and paste wholly or partly) the functionality therein.</p>
+
+<p>However, the content of this document itself may not be modified in any way, including by removing the copyright notice or references to Ecma International, except as required to translate it into languages other than English or into a different format.</p>
 
-<p>This disclaimer is valid only prior to final version of this document. After approval all rights on the standard are reserved by Ecma International.</p>
+<p>The official version of an Ecma International document is the English language version on the Ecma International website. In the event of discrepancies between a translated version and the official version, the official version shall govern.</p>
 
-<p>The limited permissions are granted through the standardization phase and will not be revoked by Ecma International or its successors or assigns during this time.</p>
+<p>The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or assigns.</p>
 
-<p>This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p>
+<p>This document and the information contained herein is provided on an “AS IS” basis and ECMA INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.</p>
 </div>
         <h2>Software License</h2>
         <p>All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT <a href="https://ecma-international.org/memento/codeofconduct.htm">https://ecma-international.org/memento/codeofconduct.htm</a> FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.</p>