Abstract
A document that uses polyglot markup is 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. Polyglot markup that meets a well defined set of
constraints is interpreted as compatible, regardless of whether they are
processed as HTML or as XHTML, per the HTML5 specification. Polyglot
markup uses a specific DOCTYPE, namespace declarations, and a specific
case—normally lower case but occasionally camel case—for element and
attribute names. Polyglot markup uses lower case for certain attribute
values. Further constraints include those on empty elements, named
entity references, and the use of scripts and style.
Status of This Document
This section describes the status of this document at the time of
its publication. Other documents may supersede this document. A list of
current W3C publications and the latest revision of this technical
report can be found in the W3C technical
reports index at http://www.w3.org/TR/.
This document summarizes design guidelines for authors who wish their
XHTML or HTML documents to validate on either HTML or XML parsers,
assuming the parsers to be HTML5-compliant. This specification is
intended to be used by web authors. It is not a specification for user
agents and creates no obligations on user agents. Note that this
recommendation does not define how HTML5-conforming user agents should
process HTML documents. Nor does it define the meaning of the Internet
Media Type text/html. For user agent guidance and for these definitions,
see [HTML5]
and [RFC2854].
This document was published by the
HTML working group as a Working Draft. This document is intended to
become a W3C Recommendation. Please submit comments regarding this
document by using the W3C's public bug database (
http://www.w3.org/Bugs/Public/) with the product set to HTML WG
and the component set to
HTML/XHTML Compatibility Authoring Guide (ed: Eliot Graff).
If you cannot access the bug database, submit comments to
[email protected]@w3.org
(subscribe,
archives) and arrangements will be made to transpose the comments to
the bug database. All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite
this document as other than work in progress.
This document was produced by a group operating under the
5 February 2004 W3C Patent Policy. W3C maintains a
public list of any patent disclosures made in connection with the
deliverables of the group; that page also includes instructions for
disclosing a patent. An individual who has actual knowledge of a patent
which the individual believes contains
Essential Claim(s) must disclose the information in accordance with
section 6 of the W3C Patent Policy.
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 either UTF-8 or UTF-16. UTF-8 is preferred. When
polyglot markup uses UTF-16, it
must not include a BOM. When polyglot markup uses UTF-16, it
must include the BOM indicating little-endian UTF-16 or big-endian
UTF-16.
Polyglot markup declares character encoding one of two ways:
Using <meta charset="*"/> has no effect in XML. Therefore,
polyglot markup may use <meta
charset="*"/> in combination with BOM, as long the meta element
specifies the same character encoding as the BOM. In addition, the meta
tag may be used in the absence of a
BOM as long as it matches the already specified encoding. Note that the
W3C Internationalization (i18n) Group recommends
to always include a visible encoding declaration in a document, because
the declaration helps developers, testers, or translation production
managers to check the encoding of a document visually.
4. The DOCTYPE
Polyglot markup must have a
document type declaration (DOCTYPE) specified by
section 8.1.1 of [HTML5].
In addition, the DOCTYPE must
conform 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,
the string must be in
lowercase, as required by HTML5.
- If the URI is an http URL, the URI must point to the correct
resource, using case-sensitive letters.
Note that polyglot markup cannot 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.
5.1 Element-Level Namespaces
[HTML5]
introduces undeclared (native) default namespaces for the root HTML
element <html>, the root SVG element <svg>,
and the root MathML element <math>. The following
default namespaces must be
declared in polyglot markup, to maintain XML-compatibility [XML10]:
<html xmlns="http://www.w3.org/1999/xhtml"><math xmlns="http://www.w3.org/1998/Math/MathML"><svg xmlns="http://www.w3.org/2000/svg">
Polyglot markup must not
declare any other default or prefixed element namespace, because [HTML5]
does not natively support the declaring of any other default or
prefixed element namespace.
5.2 Attribute-Level Namespaces
[HTML5]
introduces undeclared (native) support for attributes in the XLink
namespace and with the prefix xlink:. Polyglot markup
must declare the XLink namespace on the HTML root element (<html>)
or once on the foreign element where is used (<svg> or
<mathml>), to maintain XML-compatibility [XML10].
In polyglot markup, the xlink prefix uses the namespace declaration
xmlns:xlink="http://www.w3.org/1999/xlink"
before using the xlink prefix for the following elements:
xlink:actuatexlink:arcrolexlink:hrefxlink:rolexlink:showxlink:titlexlink:type
Furthermore, polyglot markup defines the xlink prefix only on
foreign elements (any SVG or MathML element) but not the root
<html> element or any other HTML element.
Note that there are other prefixed attributes that can be used
beyond xlink:href (such as xml:base).
Polyglot markup does not declare these prefixes via xmlns. The
prefixes are implicitly declared in XML and are automatically
applied to the appropriate attributes in HTML.
6. Elements
Polyglot markup conforms to the following rules regarding elements.
6.1 Required Elements
Polyglot markup must
explicitly have a tbody element surrounding groups of
tr
elements within a table element. HTML parsers insert
the tbody element, but XML parsers do not, thus
creating different DOMs.
Correct:
<table>
<tbody>
<tr>...
Incorrect:
<table>
<tr>...
Polyglot markup must
explicitly have a colgroup element surrounding groups
of
col elements within a table element. HTML
parsers insert the colgroup element, but XML parsers do
not, thus creating different DOMs.
Correct:
<table>
<colgroup>
<col>...
Incorrect:
<table>
<col>...
6.2 Elements that Cannot Be Used in Polyglot
Markup
Polyglot markup does not use the <noscript> element,
because the <noscript> element must not be used in XML
documents. [HTML5]
6.3 Case-Sensitivity
The following guidelines apply to any usage of element names,
attribute names, or attribute values in markup, script, or CSS.
Polyglot markup uses lower case letters for all ASCII letters. For
non-ASCII letters—such as Greek, Cyrillic, or non-ASCII Latin
letters—polyglot markup respects case sensitivity as it is called
for.
6.3.1 Element Names
Polyglot markup uses the correct case for element names.
- Polyglot markup uses lowercase letters for all HTML element
names.
- Polyglot markup uses lowercase letters for all MathML
element names.
- Polyglot markup uses lowercase letters for all SVG
element names except the following, which
must be in mixed case:
altGlyphaltGlyphDefaltGlyphItemanimateColoranimateMotionanimateTransformclipPathfeBlendfeColorMatrixfeComponentTransferfeCompositefeConvolveMatrixfeDiffuseLightingfeDisplacementMapfeDistantLightfeFloodfeFuncAfeFuncBfeFuncGfeFuncRfeGaussianBlurfeImagefeMergefeMergeNodefeMorphologyfeOffsetfePointLightfeSpecularLightingfeSpotLightfeTilefeTurbulenceforeignObjectglyphReflinearGradientradialGradienttextPath
6.3.2 Attribute Names
Polyglot markup uses the correct case for attribute names.
- Polyglot markup uses lowercase letters in attribute names
for all HTML elements.
- Polyglot markup uses lowercase letters in attribute names
for all MathML elements except the lowercase
definitionurl
must be changed to the mixed case definitionURL.
- Polyglot markup uses lowercase letters in attribute names
for all SVG elements except the following, which
must be in mixed case:
attributeNameattributeTypebaseFrequencybaseProfilecalcModeclipPathUnitscontentScriptTypecontentStyleTypediffuseConstantedgeModeexternalResourcesRequiredfilterResfilterUnitsglyphRefgradientTransformgradientUnitskernelMatrixkernelUnitLengthkeyPointskeySplineskeyTimeslengthAdjustlimitingConeAnglemarkerHeightmarkerUnitsmarkerWidthmaskContentUnitsmaskUnitsnumOctavespathLengthpatternContentUnitspatternTransformpatternUnitspointsAtXpointsAtYpointsAtZpreserveAlphapreserveAspectRatioprimitiveUnitsrefXrefYrepeatCountrepeatDurrequiredExtensionsrequiredFeaturesspecularConstantspecularExponentspreadMethodstartOffsetstdDeviationstitchTilessurfaceScalesystemLanguagetableValuestargetXtargetYtextLengthviewBoxviewTargetxChannelSelectoryChannelSelectorzoomAndPan
6.3.3 Attribute Values
Polyglot markup uses lowercase letters for the values of the
attributes in the following list when they exist on HTML elements.
More specifically, where required, polyglot markup
must use lower case letters for all ASCII letters in these
attribute values; however, polyglot markup respects case sensitivity
for non-ASCII letters such as Greek, Cyrillic, or non-ASCII Latin
letters. For attribute values on HTML elements other than those in
the following list, polyglot markup
may
use mixed case letters.
Because XML is case sensitive, polyglot markup also requires case to
be consistent for values between markup, DOM APIs, and CSS. In
addition, polyglot markup respects the case sensitivity of all other
attribute values. Although polyglot markup must always have
lowercase values of the attributes in the following list when they
exist on HTML elements, attributes not in this list and attributes
on non-HTML elements may have values made of mixed case letters.
Note that other specifications, such as RDFa, may place additional
restrictions on the allowed values of certain attributes.
acceptaccept-charsetalignalinkaxisbgcolorcharsetcheckedclearcodetypecolorcompactdeclaredeferdirdirectiondisabledenctypefaceframehreflanghttp-equivlanglanguagelinkmediamethodmultiplenohrefnoresizenoshadenowrapreadonlyrelrevrulesscopescrollingselectedshapetargettexttypevalignvaluetypevlink
6.4 Empty Elements
Polyglot markup uses only the elements in the following list as empty
elements.
areabasebrcolcommandembedhrimginputkeygenlinkmetaparamsource
Polyglot markup uses the minimized tag syntax for empty elements,
e.g. <br/>. The alternative syntax <br></br>
allowed by XML gives uncertain results in many existing user agents.
Given an empty instance of an element whose content model is not
EMPTY (for example, an empty title or paragraph) polyglot markup
does not use the minimized form (e.g. the document uses
<p></p> and not <p />).
Note that MathML and SVG elements may be either self-closing or
contain content.
6.5 Elements with Special Considerations
The following elements or their considerations require exceptions to
the general rules for polyglot markup.
6.5.1 White Space in <textarea>
and <pre> Elements
Within polyglot markup, the text within either a
<textarea> or <pre> element
must not begin with
white space.
7. Attributes
Because of attribute-value normalization in XML [XML10],
polyglot markup does not contain tabs, line feeds, or carriage returns
within CDATA attributes.
Polyglot markup surrounds all attribute values with quotation marks.
Attribute values may be surrounded
either by single quotation marks or by double quotation marks.
See also Attribute Values.
7.1 Disallowed Attributes
The following attributes are not allowed in polyglot markup. These
attributes have effects in documents parsed as XML but do not have
effects in documents parsed as text/html. The HTML5 spec therefore
defines them as invalid in text/html documents. [HTML5]
Note that the xml:space and xml:base
attributes are allowed on SVG and MathML elements.
7.2 Language Attributes
When using language attributes, polyglot markup
must use both the
lang and xml:lang attributes. Neither
attribute is to be used without the other, and the values for both
lang and xml:lang
must be the same.
Polyglot markup should use
the language attributes in the html element to set the
default language for the document.
8. Named Entity References
Polyglot markup uses only the following named entity references:
For entities beyond the previous list, a polyglot document 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 there are both. [CHARMOD]
9. Script and Style
Script and style commands should
be included by linking to external files rather than including them
in-line. However, polyglot markup
must 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 the proper way to include 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.
9.1 External Script and Style
Polyglot markup uses external scripts if that document's script or
style sheet uses < or & or ]]>
or --. Note that XML parsers are permitted to silently
remove the contents of comments; therefore, the historical practice
of hiding scripts and style sheets within comments to make the
documents backward compatible is likely to not work as expected in
XML-based user agents.
9.2 In-line Script and Style
If polyglot markup must use script or style commands within its
source code, either use safe content or wrap the command in a
CDATA section. However, polyglot markup does not use a
CDATA section unless it is being used within foreign content.
9.2.1 Safe Content
Safe content is content that does not contain a <
or & character. The following example is safe
because it does not contain problematic characters within
the <script> tag.
<script>document.body.appendChild(document.createElement("div"));</script>
9.2.2 Wrapping a Command in a CDATA
Section
Note that you cannot achieve same DOM in both XHTML and HTML
by using in-line commands in a CDATA section. However, this
is not usally a problem unless the code has a dependency on
the exact number of text nodes under a <script>
or <style> element. The following examples show
in-line script and style commands wrapped in a CDATA
section.
<script>
//<![CDATA[
(script goes here)
//]]>
</script>
<style>
/*<![CDATA[*/
(styles go here)
/*]]>*/
</style>
When using MathML or SVG, the parser follows the XML parsing
rules. Polyglot markup does not rely on getting a CDATA instance
from the DOM when using MathML or SVG, because the HTML parser
does not create a CDATA instance in the DOM.
10. Exceptions from the Foreign Content Parsing
Rules
A. Acknowledgements
Many thanks to Daniel Glazman, Richard Ishida, Tony Ross, Sam Ruby,
Jonas Sicking, Leif Halvard Silli, Henri Sivonen, Manu Sporny, and
Philip Taylor. Special thanks to the W3C TAG and the W3C
Internationalization (i18n) Core Working Group.