Use <code> element inside the <pre> elements with code examples

[Zirro]

For semantic purposes, the specification suggests that code elements be used inside pre elements which contain code. This is currently not the case for the code examples presented throughout the specification.

[annevk]

cc @sideshowbarker

[sideshowbarker]

So I made comments about this at #3768 (review).

I don’t support adding code children to all the pre elements. It’s not necessary and in fact we have some evidence that it may actually measurably more harmful than not using code children in pre.

See @tabatkins comment at #2751 (comment), where he indicates that the CSS specs are very intentionally not using code children in their pre blocks because:

Probably for the same reason we just use pre in the CSS specs - <pre><code> makes the magical-newline-omitting of pre work even worse than pre by itself.

So I think the change we instead should be making here is to update the suggestions and examples in the spec to align with what most authors actually seem to be doing (and what the CSS specs are doing) — that is, to not suggest using code children as the first child of every single pre element that has an example of JavaScript or HTML or CSS or whatever in it.

I’ll create a PR with a patch for that.

[prlbr]

<pre><code> makes the magical-newline-omitting of pre work even worse than pre by itself.

What does that actually mean? Can someone please provide examples?

[sideshowbarker]

See #3772

[sideshowbarker]

OK, upon further consideration I’m dropping my objection to this, and I have a patch ready to land that aligns with this, by adding support to Wattsi for sending code contents thru the highlighter pipeline in the case where the code element has a class value with idl, js, css, or html.

[tabatkins]

[magical newline behavior, and how code harms it]

See test at http://software.hixie.ch/utilities/js/live-dom-viewer/saved/6008. A plain pre automatically swallows a starting and ending newline in its text content, but if you wrap the content in a code, the swallowing behavior isn't identical (and generally worse).

[prlbr]

Thank you @tabatkins! The behaviour of leading and trailing newlines is inconsistent indeed. Trying to make it more consistent would affect too many legacy sites I suppose? – especially as this is not specific to <pre> vs. <pre><code>, but the same behaviour occurs in combination with other inline markup like <pre><span> too.

I don’t think this is a big enough reason to not recommend using <pre><code> for code blocks anymore. <pre><code> is semantically sound and works (just a little different than <pre> alone if there’s a leading newline inside).

[Zirro]

Thanks for providing these details @tabatkins! That is rather interesting. I suppose this behaviour is defined implicitly somewhere in the HTML parser spec?

but if you wrap the content in a code, the swallowing behavior isn't identical (and generally worse)

If it remains true that it only affects newlines at the beginning or end of the text in the situations where it happens at all, I'm happy to report that this shouldn't be a significant issue in this case. Out of the 1027 code samples with pre followed by code in the spec, only 14 of them have newlines directly before or after their content.

When I next have time to update the pull request - hopefully later this week, I will remove these and verify that the rendering still looks as intended.