propose example attribute for documentation and other uses

[Nick-Levinson]

For communicating about HTML, teaching it, or other purposes, with an example that should not cause an actual effect in a user agent, even a user agent programmed for private use, an attribute should be specified for the purpose and HTML should specify it. I propose "example" for an attribute for any element.

Case and the use of quotation marks would be as HTML specifies for other attributes. The content value could be any value, including null and absent (no equals sign) and would be formattable as for any other attribute.

The content or its absence would not be processed by a user agent.

HTML 5.1 2d ed. already has room for this ("[f]or generic extensions that are to be used by multiple independent tools, either this specification should be extended to provide the feature explicitly, or . . ." (section 3.2.5.9)).

An analogy is with domain names, such as example.com and *.test.

[chaals]

There is the obsolete and non-conforming <xmp> element that does this.

It happens to work in a lot of browsers I tested.

But a better approach MHO is to use <code> (and <pre> if you want to preserve whitespace), with escaped characters.

[iandevlin]

I agree with @chaals here, <code> currently serves this purpose well enough.

[Nick-Levinson]

No; the misunderstanding was not intended. The code and pre elements do affect browser behavior; that is precisely why they won't work for this purpose. The xmp was inconsistently implemented, which means it was at least in some browsers causing effects; that's not wanted for this proposed element (from issue 1041 combined with this issue) and this proposed attribute. This is for use in documentation where someone, like a student, might copy it into a Web page and it should still have no effect.

By reserving it, future use in a spec and private use, if conflicting, would be barred.

Visit the website at example.com and you'll see no ads, tracking of user behavior, or other things that might confuse someone for whom that should only be an example website domain. It's why you can't use domain names like mydomain.com as if they were example.com. Example.com and a few others are reserved in an RFC so that you can't buy them. That's the analogy to this proposal.

[chaals]

The problem is that you have an opt-in situation - unless a user agent understand example, it will interpret that as an unknown, and the content of it - most paticularly things like script elements - will be parsed as real content. Reserving the name won't have an effect until generations of browsers have passed...

That process has been happening for <xmp>, for years already.

I think it makes far more sense to consider whether <xmp> is sufficiently well deployed in reality that it can be safely resurrected than to start today trying to make something that does more or less the same thing - specifically because I think the proposal doesn't solve any of the significant problems differently.

The reason I prefer <code> (with or without <pre>) is that you can put semantic markup inside it, e.g. linking or empahsising bits of a code sample. You cannot do that with something like <xmp>.

I have written (in MS Word macro!) a converter to copy HTML source and paste it as escaped <code>. It's not very hard, and using DOM today you could do an even better job relatively easily - certainly easily enough for use in authoring tools.

[Nick-Levinson]

The browser doing nothing would be precisely the effect desired. HTML parsing is supposed to ignore unknown elements and (I think) unknown attributes and continue parsing as if the unknown things were not there. While that could be achieved now by inventing an element or attribute, say, xyz, if the HTML spec later adds xyz then the old xyz would suddenly acquire an unintended meaning. Reserving would prevent that. This isn't for writing a Web page that, when displayed on the Web, has a section that is parsed differently. For instance, if you want to show a stupid way of not writing HTML, existing elements and styles would be better. But if you want to write about how elements work without your sample being parsed now or in a future browser, just displayed as written, and granted you might want to use ampersand coding, then you'd want an element that's not defined now and won't be later. Likewise, if you were writing in a book and someone were to type it into a text editor, you might want to assure the absence of effect. The elements code and pre are useful for other uses. They should be kept in the spec. I don't know how to write JavaScript or how it gets interpreted, but my intent is that if it invokes an HTML element or attribute then this one should be treated as meaningless and parsing should continue past it. I've written macros, but not lately, and that would be an achievement for most people, and not always predictably necessary. It may be that "example" is a bad name to call it by, because an author may well expect to add a code tag for an example. It could be called try, trial, unknown, or something else. If the name was not in a present or prior version of HTML, there shouldn't be any browser that would give it an effect, and that leaves a lot of names as possibilities.

[chaals]

@Nick-Levinson I think I am failing to explain myself.

The problem I see is this:

You want to put some HTML code in the source, and see that rendered as-is in the page. E.g.

<xmp>
 <script>DoEvilThings()</script>
 <iframe srcdoc="... ..."><!-- use this for something nasty --> </iframe>
</xmp>

Should (and actually does today) show the user

 <script>DoEvilThings()</script>
 <iframe srcdoc="... ..."><!-- use this for something nasty --> </iframe>

on the webpage, instead of running the script or putting in the iframe. xmp is a reserved keyword that HTML defines, although noting it is obsolete and you should use ampersand-escaped code in a code element. This element - unlike more or less any other - stops the content from being parsed, because it i

If we created a new element, then any browser built before it was implemented would do nothing with the element, but would parse its content. So changing xmp in the above example to anythingNew would try to execute the script instead of showing the script tag and its content.

I think you are asking for the behaviour of xmp. That can be achieved, but is best done with the xmp element, since just reserving an element name doesn't stop its content being parsed. But I would argue that ampersand-escaped code is actually better - because you can still use HTML semantics to add markup inside your examples, making them more powerful while still ensuring they are not parsed as part of the document they are inside.

[Nick-Levinson]

Is it not possible for the HTML spec to require that a given element shall not be parsed by a conforming browser (already the case for an unspecified element, such as a misspelling)? If it's not possible, then my proposal is a bad one. If it is possible to forbid parsing, then old browsers are not problematic, because if the element has not been in any HTML spec then a browser, old or new, is not allowed to parse it anyway and must continue past it. My understanding of xmp is that browsers were inconsistent in implementing it, so apparently some were parsing it before it was obsoleted or deprecated. Short-term solutions are easy but the passage of time risks unexpected parsings of the same document. While it's also true that old HTML is problematic in today's browsers (I wouldn't try writing in HTML 3.x even though I'd like to support old browsers including Lynx for users with cheap old systems), this feature would not be likely to need to change a few years from now. In your post, it says "because it i", ending there. I've had problems with text vanishing in GitHub, so I sympathize. If my paragraphs are not spaced in between, that may have to do with emailing replies to the thread and my blank lines getting auto-stripped. I added more blank lines this time.

[unor]

If the goal is to display HTML as plain text, without having to escape < or > (which means it’s not possible to use HTML within), the script element can be used:

<script type="text/plain">
<p>Example <abbr>HTML</abbr> that doesn’t get parsed.</p>
</script>

(It can’t contain </script> or variations, of course.)

As it’s typically visually hidden in the CSS, you need to make it visible:

script[type="text/plain"] {display:block;}

[Nick-Levinson]

Those limitations could be critical. Needing CSS for visibility is a problem for students who may have little familiarity with CSS. Not allowing HTML markup (even if ineffectual) or a script tag within is too restrictive for some uses. Having to add the attribute to the element complicates usage by newbies. I think this use of the script element would have to be defined in the spec so it doesn't fail validation and so browsers and other user agents accept this use. And, by the way, I don't know how to write scripts (I haven't needed one in years that wasn't furnished by someone else), so, without the additional definition in the spec, I'd hardly be willing to recommend using the script element for the purpose. Thus, a new element and a new attribute specifically for this kind of use would all around be easier to implement and easier and more flexible for use.

[unor]

@Nick-Levinson

I think this use of the script element would have to be defined in the spec so it doesn't fail validation […]

It is, of course, defined in the spec (I also quoted the spec in my answer linked above):

The script element allows authors to include […] data blocks in their documents.

[…] means that the script is a data block, which is not processed.

[scottaohara]

Reading through this thread, I also agree with @chaals and @iandevlin.

Especially in the context of "For communicating about HTML, teaching it, or other purposes...", I would imagine one might want the ability to highlight/mark particular parts of a code example, which wouldn't be possible if the wrapped content was not processed by user agents.

I've created the this codepen example to illustrate using the mark element to highlight a portion of the example I want to draw attention to. This is not possible in the script type="text/plain" example, or if using xmp (not shown in the codepen)

Additionally, the script type="text/plain" would have one last quirk, where one could not have a nested </script>.

[chaals]

@Nick-Levinson wrote

Is it not possible for the HTML spec to require that a given element shall not be parsed by a conforming browser (already the case for an unspecified element, such as a misspelling)? If it's not possible, then my proposal is a bad one.

And the answer is, in the terms I believe you mean, "It is possible, but only for new browsers, and it would cause very big problems if people used it in content". An unknown element will be created, and behave much like a <span>. In particular, its children will be parsed.

I had written:

[the <xmp>] element - unlike more or less any other - stops the content from being parsed, because it i

...sorry I failed to complete that. I meant

...because it is already recognised, and specially treated by browsers and has been for some time. Since not implementing that could expose a big security issue, a la

<p>For example, don't do this:</p>

<xmp>
 <script>doSomethingTerrible()</script>
</xmp>

Whereas if the example were <script>somethingEvenWorse()</script> it doesn't even look like it should be run. (Although I am sure there are examples in reality of someone not coding carefully enough and getting caught out. Code is written by people and people make mistakes in describing what they think they want).

And you could do something like

<p>For example, don't do this:</p>

<pre><code>
 <em class="bad">&lt;script&gt;doSomethingTerrible()&lt;/script&gt;</em>
</code></pre>

So it seems you (@Nick-Levinson) agree, given the proposal does not behave as you had hoped in browsers, that we should drop it. I have marked it wontfix - feel free to close it, or if no further comment is forthcoming I will do so by and by.

[Nick-Levinson]

You're right (@scottaohara); it's defined in HTML for data block use with the proper type value (I thought I already knew roughly what the spec said). Some of the problems noted above could be resolved by retaining multiple markups for different purposes. A stable element or attribute that would deny parsing is one markup, but if parsing is desired then another markup would be applied. It might be more intuitive to define an element as a synonym of the script element with that type, a synonymous element that would not need an explicit attribute even though it would be a synomym of an element that has a certain attribute. @chaals, If user agents are commonly parsing as HTML elements that differ from what's in the HTML spec, I thought that was forbidden, but I can't find that now in a quick look through the spec and, given Microsoft's long history of nonconformance in IE with doing what they thought was better tus forcing designers to hack back, I'm not entirely surprised, and I don't want to break websites. So, unless the last point is wrong, please close this.

[chaals]

They are doing what the spec says - the element turns into an unknown Element - but crucially for this case its children get parsed if they are recognised. Please be careful apportioning blame for things you don't like - this group aims to avoid such things as ad hominem attacks and deal with technical issues.