Clarify template content model and syntax

This change adds a link in the `template` *Content model* header
directly to the related example in the prose of the `template` section
that helps make clear why the content model is `Nothing`.

This change also adds the `template` element as a new (sixth) element
type in the HTML Syntax: Writing HTML documents: Elements section.

Fixes whatwg#3021.

source

@@ -58775,7 +58775,7 @@ not-slash     = %x0000-002E / %x0030-10FFFF
    <dd>Where <span>script-supporting elements</span> are expected.</dd>
    <dd>As a child of a <code>colgroup</code> element that doesn't have a <code data-x="attr-colgroup-span">span</code> attribute.</dd>
    <dt><span data-x="concept-element-content-model">Content model</span>:</dt>
-   <dd><span data-x="concept-content-nothing">Nothing</span>.</dd>
+   <dd><span data-x="concept-content-nothing">Nothing</span> (for clarification, <a href="#template-example">see example</a>).</dd>
    <dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
    <dd><span>Global attributes</span></dd>
    <dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
@@ -58794,15 +58794,15 @@ interface <dfn>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
 
   <p>In a rendering, the <code>template</code> element <span>represents</span> nothing.</p>
 
-  <p>The <span>template contents</span> of a <code>template</code> element are not children of the
-  element itself. Instead, they are stored in a <code>DocumentFragment</code> associated with a
-  different <code>Document</code> without a <span>browsing context</span> so as to avoid the
-  <code>template</code> contents interfering with the main <code>Document</code>. (For example, this
-  avoids form controls from being submitted, scripts from executing, and so forth.) The
-  <span>template contents</span> have <a href="#no-browsing-context">no conformance
-  requirements</a>.</p>
+  <p>The <span>template contents</span> of a <code>template</code> element <a
+  href="#template-syntax">are not children of the element itself</a>.</p>
 
-  <div class="example">
+  <p class="note">It is also possible, as a result of DOM manipulation, for a <code>template</code>
+  element to contain <code>Text</code> nodes and element nodes; however, having any is a violation
+  of the <code>template</code> element's content model, since its content model is defined as <span
+  data-x="concept-content-nothing">nothing</span>.</p>
+
+  <div class="example" id="template-example">
 
    <p>For example, consider the following document:</p>
 
@@ -58852,8 +58852,10 @@ interface <dfn>HTMLTemplateElement</dfn> : <span>HTMLElement</span> {
   <div w-nodev>
 
   <p>Each <code>template</code> element has an associated <code>DocumentFragment</code> object that
-  is its <dfn>template contents</dfn>. When a <code>template</code> element is created, the user
-  agent must run the following steps to establish the <span>template contents</span>:</p>
+  is its <dfn>template contents</dfn>. The <span>template contents</span> have <a
+  href="#no-browsing-context">no conformance requirements</a>. When a <code>template</code> element
+  is created, the user agent must run the following steps to establish the <span>template
+  contents</span>:</p>
 
   <ol>
 
@@ -98385,9 +98387,10 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
 
   <h4>Elements</h4>
 
-  <p>There are five different kinds of <dfn data-x="syntax-elements">elements</dfn>: <span>void
-  elements</span>, <span>raw text elements</span>, <span>escapable raw text elements</span>,
-  <span>foreign elements</span>, and <span>normal elements</span>.</p>
+  <p>There are six different kinds of <dfn data-x="syntax-elements">elements</dfn>: <span>void
+  elements</span>, <span>the <code data-x="">template</code> element</span>, <span>raw text
+  elements</span>, <span>escapable raw text elements</span>, <span>foreign elements</span>, and
+  <span>normal elements</span>.</p>
 
   <dl>
 
@@ -98400,6 +98403,9 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
    <!-- non-conforming elements treated as void by the parser are not listed here: basefont,
    bgsound, frame, keygen -->
 
+   <dt><dfn>The <code data-x="">template</code> element</dfn></dt>
+   <dd><code>template</code></dd>
+
    <dt><dfn>Raw text elements</dfn></dt>
 
    <dd><code>script</code>, <code>style</code></dd> <!-- iframe and noscript don't count as raw text
@@ -98443,6 +98449,19 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
   <p><span>Void elements</span> can't have any contents (since there's no end tag, no content can be
   put between the start tag and the end tag).</p>
 
+  <p id="template-syntax"><span>The <code data-x="">template</code> element</span> can have
+  <span>template contents</span>, but such <span>template contents</span> are not children of the
+  <code>template</code> element itself. Instead, they are stored in a <code>DocumentFragment</code>
+  associated with a different <code>Document</code> — without a <span>browsing context</span> — so
+  as to avoid the <code>template</code> contents interfering with the main <code>Document</code>.
+  The markup for the <span>template contents</span> of a <code>template</code> element is placed
+  just after the <code>template</code> element's start tag and just before <code>template</code>
+  element's end tag (as with other elements), and may consist of any <span
+  data-x="syntax-text">text</span>, <span data-x="syntax-charref">character references</span>, <span
+  data-x="syntax-elements">elements</span>, and <span data-x="syntax-comments">comments</span>, but
+  but the text must not contain the character U+003C LESS-THAN SIGN (&lt;) or an <span
+  data-x="syntax-ambiguous-ampersand">ambiguous ampersand</span>.</p>
+
   <p><span>Raw text elements</span> can have <span data-x="syntax-text">text</span>, though it has <a
   href="#cdata-rcdata-restrictions">restrictions</a> described below.</p>