Polyglot Markup: HTML-Compatible XHTML Documents

Table of Contents

• 1. Introduction
• 2. Processing Instructions and the XML Declaration
• 3. Specifying a Document's Character Encoding
• 4. The DOCTYPE
• 5. Namespaces
  • 5.1 Element-Level Namespaces
  • 5.2 Attribute-Level Namespaces
• 6. Elements
  • 6.1 Required Elements
  • 6.2 Elements that Cannot Be Used in Polyglot Markup
  • 6.3 Case-Sensitivity
    • 6.3.1 Element Names
    • 6.3.2 Attribute Names
    • 6.3.3 Attribute Values
  • 6.4 Void Elements
  • 6.5 Elements with Special Considerations
    • 6.5.1 HTTP Headers and http-equiv Declarations
      • 6.5.1.1 Content-Language
      • 6.5.1.2 Content-Type
    • 6.5.2 Newlines in textarea and pre Elements
• 7. Attributes
  • 7.1 Disallowed Attributes
  • 7.2 Language Attributes
  • 7.3 Attributes with Special Considerations
    • 7.3.1 The id Attribute
• 8. Named Entity References
• 9. Script and Style
  • 9.1 External Script and Style
  • 9.2 In-line Script and Style
• 10. Comments in Polyglot Markup
• 11. Exceptions from the Foreign Content Parsing Rules
• 12. Example Document
• A. Acknowledgements
• B. References
  • B.1 Normative references
  • B.2 Informative references

2. Processing Instructions and the XML Declaration

Processing Instructions and the XML Declaration are both forbidden in polyglot markup.

3. Specifying a Document's Character Encoding

Polyglot markup uses the UTF-8 character encoding, the only character encoding for which both HTML and XML require support. HTML requires UTF-8 to be explicitly declared to avoid fallback to a legacy encoding [HTML5]. For XML, UTF-8 is an encoding default. As such, character encoding may be left undeclared in XML with the result that UTF-8 is still supported [XML10].

Polyglot markup declares the UTF-8 character encoding in the following ways, which may be used separately or in combination:

• Within the document
  • By using the Byte Order Mark (BOM) character (preferred).
  • By using <meta charset="UTF-8"/> (the HTML encoding declaration).
• Outside the document
  • By adding "charset=utf-8" to the MIME/HTTP Content-Type header [HTTP11], as the following examples show in HTML and XML, respectively:

  Content-type: text/html; charset=utf-8

  Content-type: application/xhtml+xml; charset=utf-8

The HTML encoding declaration has no effect in XML. When the HTML encoding declaration is the only encoding declaration, the encoding default from XML makes XML parsers treat content as UTF-8.

The W3C Internationalization (i18n) Group recommends to always include a visible encoding declaration in a document, because it helps developers, testers, or translation production managers to check the encoding of a document visually.

4. The DOCTYPE

Polyglot markup uses a document type declaration (DOCTYPE) specified by section 8.1.1 of [HTML5]. In addition, the DOCTYPE conforms to the following rules:

• The string DOCTYPE is in uppercase letters.
• The string html is in lowercase letters.
• The string SYSTEM, if present, is in uppercase letters.
• The string PUBLIC, if present, is in uppercase letters.
• A Formal Public Identifier (FPI), if present, is a case-sensitive match of the registered FPI to which it points.
• A URI, if present in the document type declaration, is a case-sensitive match of the URI to which it points.
  • If the URI is the string about:legacy-compat, polyglot markup includes the string in lowercase letters, as required by HTML5.
  • If the URI is an http URL, the URI points to the correct resource, using case-sensitive letters.

Note that using about:legacy-compat in XML may yield unpredictable parsing results, depending on the XML processing pipeline.

Polyglot markup does not use document type declarations for HTML4, HTML3, or HTML2, regardless of whether they contain a URI or not and regardless of their effect in HTML5 parsers, as these document type declarations are not compatible with XHTML.

5. Namespaces

The following rules apply to namespaces used in polyglot markup.

6. Elements

Polyglot markup conforms to the following rules regarding elements.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
  <head>
    <title></title>
  </head>
  <body>
  </body>
</html>

<table>
<tbody>
<tr>...

<table>
<tr>...

<table>
<colgroup>
<col>...

<table>
<col>...

HTTP header: Content-language: ru

7. Attributes

Polyglot markup surrounds all attribute values with quotation marks. Polyglot markup surrounds attribute values by either single quotation marks or by double quotation marks.

Polyglot markup does not use newline characters within an attribute.

Within an attribute's value, polyglot markup represents tabs, line feeds, and carriage returns as numeric character references rather than by using literal characters. For example, within an attribute's value, polyglot markup uses 	 for a tab rather than the literal character '\t'. This is because of attribute-value normalization in XML [XML10]. The following example uses numeric character references (escaped characters) for the line feed, tab, and less-than characters within a srcdoc attribute.

<iframe srcdoc="&lt;p>Hello &#x0A; &#x09; world!&lt;/p>" src="demo_iframe_srcdoc.htm"></iframe>

Because of attribute-value normalization in XML [XML10], polyglot markup does not use newline characters within an attribute. Practically speaking, for source code with newlines within attributes, DOMs generated via XML and HTML will be different; however, whitespace differences have no behavioral impact on the page unless explicitly examined by JavaScript, rendering the differences of small consequence. Note that newlines are overtly not allowed in the title attribute or in any attribute containing a URI.

See also Attribute Values.

8. Named Entity References

Polyglot markup uses only the following named entity references:

• amp
• lt
• gt
• apos
• quot

For entities beyond the previous list, polyglot markup uses character references. For example, polyglot markup uses   instead of  . Note that polyglot markup may use decimal values for escape characters (such as   in the previous example); however, the Character Model for the World Wide Web recommends that content should use the hexadecimal form of character escapes rather than the decimal form when both are available. [CHARMOD]

Polyglot markup always uses character references for the less than sign (<) and ampersand (&) when they are used as characters, except when those characters appear inside a CDATA section.

9. Script and Style

Polyglot markup includes script and style commands by linking to external files rather than including them in-line. Polyglot markup does not link to an external stylesheet by using the xml-stylesheet processing instruction. See also Processing Instructions and the XML Declaration.

The following examples show how polyglot markup includes external script and style, respectively:

<script src="external.js"></script>

<link rel="stylesheet" href="external.css"/>

Although document.write() and document.writeln() are valid in an HTML document, neither function may be used in XHTML. Therefore, neither is used in polyglot markup. Instead, use the innerHTML property for both HTML and XHTML. Note that the innerHTML property takes a string. XML parsers parse the string as XML in XHTML. HTML parsers parse the string as HTML in HTML. Because of the difference in parsing, if you send the parser content that does not follow the rules for polyglot markup the results will differ for a DOM create with an XML parser and one created with an HTML parser.

<script>document.body.appendChild(document.createElement("div"));</script>

10. Comments in Polyglot Markup

Polyglot markup does not begin a comment with either ">" or "->".

11. Exceptions from the Foreign Content Parsing Rules

12. Example Document

The following example code acts as polyglot markup and validates as either XHTML or as HTML. You can view the page live at http://dev.w3.org/html5/html-xhtml-author-guide/SamplePage.html.

<!DOCTYPE html>


<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

  <head>
    <title>A Sample Page Using Polglot Markup</title>
	<!-- The link element is self-closing as described in Section 6.4 Void Elements -->
	<!-- Style commands are included by linking to an external file rather than including them in-line, 
	  as described in Section 9. Script and Style -->
	<link type="text/css" rel="stylesheet" href="Sample.css"/>
  </head>

  <body>
    <h1>Sample Page Using Polyglot Markup</h1>
    <p>
      The source code for this document uses polyglot markup, 
      a document that is a stream of bytes that parses into identical document trees 
      (with the exception of the xmlns attribute on the root element) when processed as HTML and when processed as XML.
      The source code for this document also contains additional comments about the use of 
      polyglot markup.
    </p>
		
    <h2>Foreign Elements</h2>
    <p>
      The following shapes use SVG elements.
      Polyglot markup introduces undeclared (native) default namespaces 
      for the the root SVG element (<svg>) and respects the mixed-case element names and values 
      when appropriate, as described in sections 5.1 Element-Level Namespaces, 
      6.3.1 Element Names, and 6.3.3 Attribute Values.
    </p>

    <!-- Polyglot markup declares the xlink: namespace on the <svg> element to maintain XML-compatibility  -->
    <svg width="350" height="250" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
      <g>
        <title>Three SVG shapes</title>
        <desc>
          This SVG image contains an ellipse filled with a gradient that goes from white to blue as it moves outward from the center. 
          A yellow rectangle with a black border overlaps the ellipse in the upper-left quadrant, 
          and a red spiral on a white background overlaps the ellipse in the bottom-right quadrant. 
          The red spiral is also a link to the example code for that SVG shape.
        </desc>
        <defs>
          <!-- Note that "radialGradient" and "myGradient" respect mixed-case values. -->
          <radialGradient id="myGradient" cx="50%" cy="50%" r="50%" fx="50%" fy="50%">
            <stop offset="0%" style="stop-color:rgb(200,200,200); stop-opacity:0"/>
            <stop offset="100%" style="stop-color:rgb(0,0,255); stop-opacity:1"/>
          </radialGradient>
        </defs>
      <ellipse cx="50%" cy="50%" rx="50%" ry="42%" style="fill:url(#myGradient)"/>
      <rect x="0" y="0" width="100" height="100" style="fill: yellow; stroke: black;"/> 
      <a xlink:href="http://www.w3schools.com/svg/tryit.asp?filename=path2&type=svg">
        <!-- Note that the following attribute contains no newlines. -->
        <path  transform="translate(60, -175)" d="M153 334 C153 334 151 334 151 334 C151 339 153 344 156 344 C164 344 171 339 171 334 C171 322 164 314 156 314 C142 314 131 322 131 334 C131 350 142 364 156 364 C175 364 191 350 191 334 C191 311 175 294 156 294 C131 294 111 311 111 334 C111 361 131 384 156 384 C186 384 211 361 211 334 C211 300 186 274 156 274" style="fill:white;stroke:red;stroke-width:2"/>
        </a>
      </g>
    </svg> 		
    <h2>Void Elements</h2>
    <!-- Given an empty instance of an element whose content model is not EMPTY (in this case, an empty paragraph) 
    polyglot markup does not use the minimized form, as described in Section 6.4 Void Elements -->
    <p></p>
    <p>
      There is an empty <p> element before this paragraph. 
      Polyglot markup uses <p></p> and not <p />.  
    </p>
    <p>
      Polyglot markup treats certain elements as self-closing, 
      void elements, such as the following <img> element.
    </p>
    <img height="48" width="72" alt="W3C" src="http://www.w3.org/Icons/w3c_home"/>
    <p>
      For more information, see Section 6.4 Void Elements.
    </p>


    <h2>Required Elements</h2>
    <p>
      The following table uses the required <tbody> element, as described in 
      Section 6.1 Required Elements.
    </p>
    <table>
      <tbody>
        <tr>
          <th>Column One</th>
          <th>Column Two</th>
        </tr>
        <tr>
          <td>Row 1, Column 1</td>
          <td>Row 1, Column 2</td>
        </tr>
        <tr>
          <td>Row 2, Column 1</td>
          <td>Row 2, Column 2</td>
        </tr>
        <tr>
          <td>Row 3, Column 1</td>
          <td>Row 3, Column 2</td>
        </tr>
      </tbody>
    </table>

    <p>
      The following table uses the required <colgroup> element, as described in 
      Section 6.1 Required Elements.  
    </p>
    <table>
      <colgroup>
        <col style="background-color:silver"/>
        <col style="background-color:gray"/>
        <col style="background-color:yellow"/>
      </colgroup>
      <tbody>
        <tr>
          <th>ISBN</th>
          <th>Title</th>
          <th>Price</th>
        </tr>
        <tr>
          <td>3476896</td>
          <td>My first HTML</td>
          <td>$53</td>
        </tr>
        <tr>
          <td>1234567</td>
          <td>Intermediate Polyglot</td>
          <td>$49</td>
        </tr>
      </tbody>
    </table>

    <h2>Named Entity References</h2>
    <p>
      This paragraph uses the string "&amp;" for ampersands ("&") and uses the string "&#xA0;" 
      for a nonbreaking space between the words "polyglot markup," as described in 
      Section 8. Named Entity References.
    </p>
  </body>
</html>