Add many document options.

tc39 · Sep 26, 2015 · 9db33ae · 9db33ae
1 parent be601a4
commit 9db33ae
Show file tree

Hide file tree

Showing 12 changed files with 156 additions and 10 deletions.
diff --git a/css/elements.css b/css/elements.css
@@ -206,6 +206,20 @@ emu-gprose {
     font-family: Helvetica, Arial, sans-serif;
 }
 
+h1.shortname {
+  color: #f60;
+  font-size: 1.5em;
+  margin: 0;
+}
+h1.version {
+  color: #f60;
+  font-size: 1.5em;
+  margin: 0;
+}
+h1.title {
+  margin-top: 0;
+  color: #f60;
+}
 h1, h2, h3, h4, h5, h6 {
     position: relative;
 }

diff --git a/lib/Spec.js b/lib/Spec.js
@@ -27,6 +27,9 @@ const clauseTextNodesUnder = utils.textNodesUnder(NO_CLAUSE_AUTOLINK);
 const NO_ALG_AUTOLINK = ['PRE', 'CODE', 'EMU-XREF'];
 const algTextNodesUnder = utils.textNodesUnder(NO_ALG_AUTOLINK);
 
+const DRAFT_DATE_FORMAT = { year: 'numeric', month: 'long', day: 'numeric' };
+const STANDARD_DATE_FORMAT = { year: 'numeric', month: 'long' };
+
 module.exports = class Spec {
   constructor (rootPath, fetch, doc, opts) {
     opts = opts || {};
@@ -110,6 +113,7 @@ module.exports = class Spec {
 
   build() {
     let p = this.buildAll('emu-import', Import)
+      .then(this.buildBoilerplate.bind(this))
       .then(this.loadES6Biblio.bind(this))
       .then(this.loadBiblios.bind(this))
       .then(this.buildAll.bind(this, 'emu-clause, emu-intro, emu-annex', Clause))
@@ -196,7 +200,7 @@ module.exports = class Spec {
 
   exportBiblio() {
     if (!this.opts.location) {
-      utils.logWarning('no spec location specified. Biblio not generated. Try --location or setting the location in the document\'s metadata block.');
+      utils.logWarning('No spec location specified. Biblio not generated. Try --location or setting the location in the document\'s metadata block.');
       return {};
     }
 
@@ -224,6 +228,60 @@ module.exports = class Spec {
     }
   }
 
+  buildBoilerplate() {
+    const status = this.opts.status || 'proposal';
+    const version = this.opts.version;
+    const title = this.opts.title;
+    const shortname = this.opts.shortname;
+    const stage = this.opts.stage === undefined ? null : String(this.opts.stage);
+
+    // 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 = title;
+      this.doc.head.appendChild(titleElem);
+
+      const h1 = this.doc.createElement('h1');
+      h1.setAttribute('class', 'title');
+      h1.innerHTML = title;
+      this.doc.body.insertBefore(h1, this.doc.body.firstChild);
+    }
+
+    // version string, ala 6th Edition July 2016 or Draft 10 / September 26, 2015
+    let versionText = '';
+    if (version) {
+      versionText += version + ' / ';
+    } else if (status === 'proposal' && stage) {
+      versionText += 'Stage ' + stage + ' Draft / ';
+    }
+
+    const defaultDateFormat = status === 'standard' ? STANDARD_DATE_FORMAT : DRAFT_DATE_FORMAT;
+    const date = this.opts.date || new Intl.DateTimeFormat('en-US', defaultDateFormat).format(new Date());
+    versionText += date;
+
+    if (!this._updateBySelector('h1.version', versionText)) {
+      const h1 = this.doc.createElement('h1');
+      h1.setAttribute('class', 'version');
+      h1.innerHTML = versionText;
+      this.doc.body.insertBefore(h1, this.doc.body.firstChild);
+    }
+
+    // shortname and status, ala 'Draft ECMA-262
+    if (shortname) {
+      const shortnameText = status.charAt(0).toUpperCase() + status.slice(1) + ' ' + shortname;
+
+      if (!this._updateBySelector('h1.shortname', shortnameText)) {
+        const h1 = this.doc.createElement('h1');
+        h1.setAttribute('class', 'shortname');
+        h1.innerHTML = shortnameText;
+        this.doc.body.insertBefore(h1, this.doc.body.firstChild);
+      }
+    }
+  }
+
   autolink() {
     this._log('Autolinking terms and abstract ops...');
     const termlinkmap = {};
@@ -294,6 +352,20 @@ module.exports = class Spec {
     if (!this.opts.verbose) return;
     utils.logVerbose(str);
   }
+
+  _updateBySelector(selector, contents) {
+    const elem = this.doc.querySelector(selector);
+    if (elem && elem.textContent.trim().length > 0) {
+      return true;
+    }
+
+    if (elem) {
+      elem.innerHTML = contents;
+      return true;
+    }
+
+    return false;
+  }
 };
 
 

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ecmarkup",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Custom element definitions and core utilities for markup that specifies ECMAScript and related technologies.",
   "main": "lib/ecmarkup.js",
   "scripts": {

diff --git a/spec/index.html b/spec/index.html
@@ -5,7 +5,6 @@
 <link rel="stylesheet" href="elements.css">
 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.4/styles/solarized_light.min.css">
 <pre class=metadata>
-title: Ecmarkup Documentation
 repository: https://github.com/bterlson/ecmarkup
 </pre>
 <emu-biblio href="./biblio.json"></emu-biblio>
@@ -37,16 +36,28 @@ <h1>Getting Started</h1>
 
   <emu-clause id="useful-options">
     <h1>Useful Options</h1>
-    <p>These options can be passed in via the command line or specified in the front-matter of your document.</p>
-    <emu-table>
-      <emu-caption>Listing of available options</emu-caption>
+    <p>Build options and document options can be passed in via the command line or specified in the front-matter of your document.</p>
+    <emu-table id="build-options">
+      <emu-caption>Build options</emu-caption>
       <table>
         <tr><th>Option</th><th>Description</th></tr>
         <tr><td>watch</td><td>Rebuild when files change</td></tr>
         <tr><td>verbose</td><td>Print verbose logging info</td></tr>
         <tr><td>biblio</td><td>Emit a biblio file to the specified location</td></tr>
         <tr><td>css</td><td>Emit the Ecmarkup CSS file to the specified location</td></tr>
         <tr><td>js</td><td>Emit the Ecmarkup JS file to the specified location</td></tr>
+      </table>
+    </emu-table>
+
+    <emu-table id="document-options">
+      <emu-caption>Document options</emu-caption>
+      <table>
+        <tr><th>Option</th><th>Description</th></tr>
+        <tr><td>title</td><td>Title of specification, for example `ECMAScript 2016` or `Async Functions`.</td></tr>
+        <tr><td>status</td><td>Status of specification. Can be `proposal`, `draft`, or `standard`. Default is `proposal`.</td></tr>
+        <tr><td>stage</td><td>Stage of proposal. Must be a number if provided, but is optional. Sets `version` to `Stage N Draft`, but can be overridden.</td></tr>
+        <tr><td>version</td><td>Version of specification, for example `6<sup>th</sup> Edition` or `Draft 1`. Optional.</td></tr>
+        <tr><td>shortname</td><td>Shortname of specification, for example `ECMA-262` or `ECMA-402`.</td></tr>
         <tr><td>location</td><td>Href of this specification. Use in conjunction with the biblio file to enable external specs to reference this one.</td></tr>
         <tr><td>toc</td><td>Emit table of contents. Boolean, default true.</td></tr>
         <tr><td>old-toc</td><td>Emit the old style of table of contents. Boolean, default false.</td></tr>
@@ -119,7 +130,7 @@ <h1>Editorial Conventions</h1>
   <h1>Metadata</h1>
   <p>There are a number of settings that allow customizations or enable generation of boilerplate. Metadata can be included in the document and passed on the command line, for example `--no-toc --title "Document 1"`. Metadata given on the command line takes precedence.</p>
   <p>To add metadata to your document, use yaml syntax inside a `&lt;pre class=metadata>` element somewhere in the root of your document.</p>
-  <p>All of the command line options can be provided in the metadata block. See the table above for a list (or consult `--help`).</p>
+  <p>All of the command line options can be provided in the metadata block. See <emu-xref href="#build-options"></emu-xref> and <emu-xref href="#document-options"></emu-xref> for a list (or consult `--help`).</p>
   <h2>Example document with metadata</h2>
 <pre><code class="language-html">
 &lt;pre class=metadata>

diff --git a/test/date.html b/test/date.html
@@ -0,0 +1,8 @@
+<pre class=metadata>
+title:     test title!
+date:      July, 2014
+toc:       false
+</pre>
+
+<p>Some body content</p>
+
diff --git a/test/date.html.baseline b/test/date.html.baseline
@@ -0,0 +1,6 @@
+<!doctype html>
+<head><title>test title!</title><meta charset="utf-8"></head><body><h1 class="version">July, 2014</h1><h1 class="title">test title!</h1>
+
+<p>Some body content</p>
+
+</body>
diff --git a/test/shortname.html b/test/shortname.html
@@ -0,0 +1,9 @@
+<pre class=metadata>
+title:     test title!
+shortname: ECMA-000
+status:    draft
+version:   Draft 1
+toc:       false
+</pre>
+
+<p>Some body content</p>
diff --git a/test/shortname.html.baseline b/test/shortname.html.baseline
@@ -0,0 +1,5 @@
+<!doctype html>
+<head><title>test title!</title><meta charset="utf-8"></head><body><h1 class="shortname">Draft ECMA-000</h1><h1 class="version">Draft 1 / September 26, 2015</h1><h1 class="title">test title!</h1>
+
+<p>Some body content</p>
+</body>
diff --git a/test/test.html b/test/test.html
@@ -1,6 +1,12 @@
 <!doctype html>
 <meta charset="utf-8">
-<link rel="stylesheet" href="https://bterlson.github.com/ecmarkup/elements.css">
+<link rel="stylesheet" href="./ecmarkup.css">
+<script src="ecmarkup.js"></script>
+<pre class="metadata">
+title:     Ecmarkup Test Document
+status:    draft
+version:   Draft 1
+</pre>
 <emu-intro>
   <h1>Intro</h1>
   <emu-intro>

diff --git a/test/test.html.baseline b/test/test.html.baseline
@@ -1,7 +1,9 @@
 <!doctype html>
 <head><meta charset="utf-8">
-<link rel="stylesheet" href="https://bterlson.github.com/ecmarkup/elements.css">
-</head><body><div id="menu-toggle">☰</div><div id="menu"><div id="menu-toc"><ol class="toc"><li><span class="item-toggle">◢</span><a href="#" title="Intro"><span class="secnum"></span> Intro</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#" title="Sub Intro"><span class="secnum"></span> Sub Intro</a></li></ol></li><li><span class="item-toggle">◢</span><a href="#" title="Clause Foo(_a_, _b_)"><span class="secnum">1</span> Clause Foo(<var>a</var>, <var>b</var>)</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#Foo" title="Sub Clause"><span class="secnum">1.1</span> Sub Clause</a></li><li><span class="item-toggle-none"></span><a href="#Bar" title="Sub Clause"><span class="secnum">1.2</span> Sub Clause</a></li><li><span class="item-toggle">◢</span><a href="#Baz" title="Header"><span class="secnum">1.3</span> Header</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#import3" title="Import 3"><span class="secnum">1.3.1</span> Import 3</a></li></ol></li></ol></li><li><span class="item-toggle-none"></span><a href="#" title="Annex"><span class="secnum">A</span> Annex</a></li></ol></div></div><emu-intro>
+<link rel="stylesheet" href="./ecmarkup.css">
+<script src="ecmarkup.js"></script>
+<title>Ecmarkup Test Document</title></head><body><div id="menu-toggle">☰</div><div id="menu"><div id="menu-toc"><ol class="toc"><li><span class="item-toggle">◢</span><a href="#" title="Intro"><span class="secnum"></span> Intro</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#" title="Sub Intro"><span class="secnum"></span> Sub Intro</a></li></ol></li><li><span class="item-toggle">◢</span><a href="#" title="Clause Foo(_a_, _b_)"><span class="secnum">1</span> Clause Foo(<var>a</var>, <var>b</var>)</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#Foo" title="Sub Clause"><span class="secnum">1.1</span> Sub Clause</a></li><li><span class="item-toggle-none"></span><a href="#Bar" title="Sub Clause"><span class="secnum">1.2</span> Sub Clause</a></li><li><span class="item-toggle">◢</span><a href="#Baz" title="Header"><span class="secnum">1.3</span> Header</a><ol class="toc"><li><span class="item-toggle-none"></span><a href="#import3" title="Import 3"><span class="secnum">1.3.1</span> Import 3</a></li></ol></li></ol></li><li><span class="item-toggle-none"></span><a href="#" title="Annex"><span class="secnum">A</span> Annex</a></li></ol></div></div><h1 class="version">Draft 1 / September 26, 2015</h1><h1 class="title">Ecmarkup Test Document</h1>
+<emu-intro>
   <h1><span class="secnum"></span>Intro<span class="utils"><span class="anchor"><a href="#">#</a></span></span></h1>
   <emu-intro>
     <h1><span class="secnum"></span>Sub Intro<span class="utils"><span class="anchor"><a href="#">#</a></span></span></h1>

diff --git a/test/title.html b/test/title.html
@@ -0,0 +1,8 @@
+<pre class=metadata>
+title:     test title!
+status:    draft
+version:   Draft 1
+toc:       false
+</pre>
+
+<p>Some body content</p>
diff --git a/test/title.html.baseline b/test/title.html.baseline
@@ -0,0 +1,5 @@
+<!doctype html>
+<head><title>test title!</title><meta charset="utf-8"></head><body><h1 class="version">Draft 1 / September 26, 2015</h1><h1 class="title">test title!</h1>
+
+<p>Some body content</p>
+</body>