This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
The current description of Transparent Elements at https://html.spec.whatwg.org/multipage/dom.html#transparent-content-models follows: Some elements are described as transparent; they have "transparent" in the description of their content model. The content model of a transparent element is derived from the content model of its parent element: the elements required in the part of the content model that is "transparent" are the same elements as required in the part of the content model of the parent of the transparent element in which the transparent element finds itself. Example […] In some cases, where transparent elements are nested in each other, the process has to be applied iteratively. Example […] When a transparent element has no parent, then the part of its content model that is “transparent” must instead be treated as accepting any flow content. I find that description very confusing. What about this one? Transparent elements are those which have the word “transparent” in at least one part of their content model. Transparent parts allow the same elements which are allowed (in those parts) in the parent element (and so on until a non-transparent part is found in the ancestors chain), unless a transparent element has no parent. In such a case, transparent parts allow any flow content. Example […] Example […]
"and so on" is unfortunately not unambiguous enough for normative prose. :-( I agree that the current text isn't great, though...
Suggestion n.2 (got rid of "and so on"): Transparent elements are those which have the word “transparent” in at least one part of their content model. A transparent part allows the same elements allowed by the closest ancestor element whose containing part is non-transparent. If no such ancestor exists then a transparent part allows any flow content. Example […] Example […] Nice, one line shorter. I love this job. :)
To make this normative, we'd need to change "allowed" to be one of the RFC2119 terms; the original text uses "required" for this. What does "containing part" mean?
I must admit that I changed from "required" to "allowed" on purpose, not by accident. IMO it makes the text lighter and much easier to read. Maybe it's only me, but when I read "allowed" I immediately get it and can focus on *what* is allowed. When instead I read "required" I imagine that the author is highlighting an obligation and I always have to read once and again the same sentence to make sure I understood it correctly. In another place on the same page we read: "Authors must not use HTML elements anywhere except where they are explicitly allowed, as defined for each element, or as explicitly required by other specifications." I think this sentence shows (1) that "must not" is to be interpreted according to RFC2119 and (2) that both allow and require make sense for this specification and have the same weight. (In that page "allow" appears 20 times, "require" 28.) Also the examples for transparent elements use "allow" instead of "require". I knew that "containing part" is a bit surprising and requires an imagination effort, but decided to use it anyway because "containment hierarchy" and "ancestors chain" are basic concepts (in our context) which remind of each other and, having used "ancestor" before in the sentence, it would have been clear what "containing" meant. In the original text "part" is not defined there either (maybe elsewhere?) but we imagine (1) that content models are made up of parts, and (2) that "transparent" can be only a part of a content model. Both of these concepts are included in the opening sentence: "Transparent elements are those which have the word “transparent” in at least one part of their content model." Thus, by using "whose containing part" I hook the "transparent part" concept onto the "containment hierarchy" concept, and everything works together. :-)
The spec carefully uses "required" when it's suppose to be RFC2119-normative, and "allowed" when it's supposed to be non-normative or part of a definition. I agree that it doesn't make the spec as easy to read as it might otherwise be; this is an intentionally trade-off between precision and approachability. It's more important that the spec be precise so we can get interoperable implementations than that it be approachable; we have tutorials for the latter that can do a much better job. I don't think the proposed text is sufficiently precise. In particular, while it's clear to me that a content model can have "parts", it's not clear to me how to define that a particular part is "containing" anything.
BTW this isn't to say that the spec is perfect or anything. I'm definitely open to improving this part of the text. (Hence why this bug is still open.)
Okay, I understand what you say and will try to improve my wording again, but now I think I need to know if you think that I correctly understood transparent elements in the first place. Do you think that my use of "containing" reveals a misunderstanding or does it only lacks precision? Now that I remember --tell me if you think this is worth a separate issue-- I collected all transparent elements I could find on the site by "find in page". I think it would be useful for readers to have this list added below the definition we are discussing.
You can find all the uses of the word "transparent" by clicking on the bold text that is in its definition. I think your understanding is correct, but I'm not 100% sure because of the lack of precision, if that makes sense. :-)
Oops, there was a 'transparent' bold word to click and I missed it? I just ran to my pc and tried it but it didn't work. At least for me, it only shows a link to self, and a link to the beginning of the section I'm already at. I found these manually: a, ins, del, object, video, audio, map, noscript, canvas.
You need to load the single-page version of the spec for it to work across the whole spec.
Andrea, do you still wish to pursue this?
It sounds like this is mostly resolved, but we're happy to reopen and continue discussion if you disagree, Andrea!