Promote emu-grammar to top level and discourage emu-production etc. (#509)

Author: gibson042

spec/index.html

@@ -657,9 +657,51 @@ <h3>Result</h3>
   </aside>
 </emu-clause>
 
+<emu-clause id="emu-grammar">
+  <h1>emu-grammar</h1>
+  <p>Text inside emu-grammar elements is parsed using <a href="https://github.com/rbuckton/grammarkdown">Grammarkdown</a>. The syntax is essentially identical to the notational conventions in ECMAScript (minus formatting). See the <a href="https://github.com/rbuckton/grammarkdown">Grammarkdown readme</a>.</p>
+  <p>Grammar will be displayed as an inline element flowing with text unless it is the immediate child of an emu-clause-like element.</p>
+
+  <h2>Attributes</h2>
+  <p><b>collapsed:</b> If present, productions are displayed in collapsed format with LHS and RHS on the same line.</p>
+  <p><b>example:</b> If present, the element is an example.</p>
+  <p><b>primary:</b> Optional: Deprecated in favor of type="definition".</p>
+  <p><b>type:</b> Optional: Disposition of the grammar. If absent, it is considered to reference productions defined elsewhere.</p>
+  <ul>
+    <li>"definition": The grammar is an authoritative source for productions which should be the target of references.</li>
+    <li>"example": Deprecated in favor of the <b>example</b> attribute.</li>
+  </ul>
+
+  <h2>Example</h2>
+  <pre><code class="language-html">
+    &lt;p>
+      &lt;emu-grammar type="definition" collapsed example>
+        HexIntegerLiteral :: `0x` HexDigits
+      &lt;/emu-grammar>
+      is a shorthand for:
+    &lt;/p>
+    &lt;emu-grammar type="definition" example>
+      HexIntegerLiteral :: `0` `x` HexDigits
+    &lt;/emu-grammar>
+  </code></pre>
+
+  <h3>Result</h3>
+  <aside class="result">
+    <p>
+      <emu-grammar type="definition" collapsed example>
+        HexIntegerLiteral :: `0x` HexDigits
+      </emu-grammar>
+      is a shorthand for:
+    </p>
+    <emu-grammar type="definition" example>
+      HexIntegerLiteral :: `0` `x` HexDigits
+    </emu-grammar>
+  </aside>
+</emu-clause>
+
 <emu-clause id="grammar">
-  <h1>Specifying Grammar</h1>
-  <p>There are two ways to specify grammar in Ecmarkup: using the <a href="#emu-production">emu-production</a> element and related elements, or by using the <a href="#emu-grammar">emu-grammar</a> element which allows specifying grammar using a plaintext format.</p>
+  <h1>Directly Specifying Grammar</h1>
+  <p>Although discouraged, it is possible to directly specify grammar using the <a href="#emu-production">emu-production</a> element and related elements emitted by <a href="https://github.com/rbuckton/grammarkdown">Grammarkdown</a>.</p>
 
   <h2>Lexical Grammar Examples</h2>
   <pre><code class="language-html">
@@ -733,48 +775,6 @@ <h3>Result</h3>
     </emu-production>
   </aside>
 
-  <emu-clause id="emu-grammar">
-    <h1>emu-grammar</h1>
-    <p>Text inside emu-grammar elements is parsed using <a href="https://github.com/rbuckton/grammarkdown">Grammarkdown</a>. The syntax is essentially identical to the notational conventions in ECMAScript (minus formatting). See the <a href="https://github.com/rbuckton/grammarkdown">Grammarkdown readme</a>.</p>
-    <p>Grammar will be displayed as an inline element flowing with text unless it is the immediate child of an emu-clause-like element.</p>
-
-    <h2>Attributes</h2>
-    <p><b>collapsed:</b> If present, productions are displayed in collapsed format with LHS and RHS on the same line.</p>
-    <p><b>example:</b> If present, the element is an example.</p>
-    <p><b>primary:</b> Optional: Deprecated in favor of type="definition".</p>
-    <p><b>type:</b> Optional: Disposition of the grammar. If absent, it is considered to reference productions defined elsewhere.</p>
-    <ul>
-      <li>"definition": The grammar is an authoritative source for productions which should be the target of references.</li>
-      <li>"example": Deprecated in favor of the <b>example</b> attribute.</li>
-    </ul>
-
-    <h2>Example</h2>
-    <pre><code class="language-html">
-      &lt;p>
-        &lt;emu-grammar type="definition" collapsed example>
-          HexIntegerLiteral :: `0x` HexDigits
-        &lt;/emu-grammar>
-        is a shorthand for:
-      &lt;/p>
-      &lt;emu-grammar type="definition" example>
-        HexIntegerLiteral :: `0` `x` HexDigits
-      &lt;/emu-grammar>
-    </code></pre>
-
-    <h3>Result</h3>
-    <aside class="result">
-      <p>
-        <emu-grammar type="definition" collapsed example>
-          HexIntegerLiteral :: `0x` HexDigits
-        </emu-grammar>
-        is a shorthand for:
-      </p>
-      <emu-grammar type="definition" example>
-        HexIntegerLiteral :: `0` `x` HexDigits
-      </emu-grammar>
-    </aside>
-  </emu-clause>
-
   <emu-clause id="emu-production">
     <h1>emu-production</h1>
     <p>This is the top level element that contains a grammar production associating a shared <dfn>LHS</dfn> (left-hand side) <emu-xref href="#emu-nt" title></emu-xref> non-terminal symbol with one or more <emu-xref href="#emu-rhs" title></emu-xref> elements containing arbitrary <dfn>RHS</dfn> (right-hand side) sequences of terminal and non-terminal symbols.</p>