Re: [w3c/DOM-Parsing] Special case innerHTML for template parsing; note for outerHTML (#12)

> @@ -416,6 +424,13 @@
>        the <a>context object</a>'s <a>next sibling</a>.
>      </dl>
>    </ol>
> +  
> +  <p class=note>No special handling for <code><a>template</a></code> elements is included in the 
> +  above "<code>afterbegin</code>" and "<code>beforeend</code>" cases. Unlike 
> +  <a for="Element">innerHTML</a>, <a for="Element">insertAdjacentHTML</a> will insert the given 
> +  <var>fragment</var> into a <code><a>template</a></code>'s <a>children</a> rather than into its
> +  <a>template contents</a>.</p>

The "Unlike..." phrasing makes it seem like `insertAdjacentHTML` is the unusual case here, when it's actually `innerHTML` (and string parsing in general) which is the special case.  Here's an attempt at a rewrite emphasizing the difference:

> As with other direct Node-manipulation APIs (and unlike `innerHTML`), `insertAdjacentHTML` does not include any special handling for `template` elements.  In most cases you will wish to use `template.content.insertAdjacentHTML` instead of directly manipulating the child nodes of a `template` element.

My idea here is to reinforce in the reader the general rule here (direct Node-manipulation APIs do not special-case `template`) and to be actively helpful in suggesting a solution if the reader reaches this point in the spec text while tracking down an apparent "bug" (`template.insertAdjacentHTML("foo")` appears to have no effect on the template contents).  Other wording suggestions welcome!

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/DOM-Parsing/pull/12/files/7bccda9963fdbc6dd7cdfb90621dffad6d5d2171#r66152428