Help developers better understand self-closing-tag syntax

[sideshowbarker]

Problem description

Many web developers have misunderstandings about self-closing-tag syntax in HTML documents. Discussions in Stack Overflow and Twitter threads and various other fora provide evidence of those misunderstandings.

Specifically, many developers misinterpret the / solidus character in an HTML-element start tag to mean that the HTML element is marked as self-closing — when in fact the HTML standard does not actually say that it marks HTML elements as self-closing but instead only marks foreign elements (SVG and MathML elements) as self-closing.

Some tool vendors — that is, some vendors of HTML formatting and authoring tools — also seem to have that same misunderstanding, which has resulted in a proliferation of tools (most notably, Prettier) that bake self-closing-tag syntax into the behavior of their tools in a way that also further proliferates misunderstandings among web developers.

On top of that, most developers are likely not aware that the / solidus character, if directly preceded by an unquoted attribute value, becomes part of the attribute value rather than being discarded by the parser.

For some related discussion that makes some important points about why all that is a real problem for developers and why we should try to help solve it, see @hsivonen’s comments at https://github.com/orgs/mdn/discussions/242#discussioncomment-3749398 and at https://github.com/orgs/mdn/discussions/242#discussioncomment-3759664.

Proposed solution

Refine the wording of the relevant text in the HTML standard to:

1. Clarify that the / solidus character in an HTML-element start tag doesn’t mark the HTML element as self-closing.

2. Explicitly caution developers that the / solidus character, if directly preceded by an unquoted attribute value, becomes part of the attribute value rather than being discarded by the parser

Notes

The relevant existing text of the HTML standard says this:

Then, if the element is one of the void elements, or if the element is a foreign element, then there may be a single U+002F SOLIDUS character (/). This character has no effect on void elements, but on foreign elements it marks the start tag as self-closing.

Note carefully: that text in the standard explicitly states that the / solidus character marks foreign elements as self-closing but that same text very intentionally (not an oversight) does not state that it marks void elements (which are elements in the HTML namespace) as self-closing.

In other words, since the standard does not explicitly state that the / solidus character marks void elements as self-closing, that means it in fact does not mark void elements as self-closing.

However, to a casual reader, that existing text in the standard risks being read with ambiguity — which is perhaps part of what’s lead to some of the misunderstandings about it among developers.

Therefore, the patch in this PR branch aims to make the relevant text in the standard unambiguous — by clearly and explicitly stating that the / solidus character does not mark a void element as self-closing (which is consistent with what’s already stated and intended by the existing text in the standard).

---

All that said, I’m not wedded to the exact wording in the initial patch in this PR branch, and would be happy if we could use this PR to iterate on any refinements to the wording that we could get rough agreement on — as long as the wording we arrive at helps to solve the problems described in the Problem Description above, and as long it includes conveying the two key points outlined in the Proposed Solution above.

---

/syntax.html ( diff )

[domenic]

LGTM, will give it a few days in case others have thoughts.