Basic Content Document Specification, Version 1.0

1.4.1 Imperative Level

The requirement level imperatives described in Section 1.3 are highlighted based on three basic imperative levels: required, recommended, and optional.

1.4.2 Elements, Attributes and Attribute Values

The normative XHTML 1.1 edition of this specification includes special markup for every mention of elements, attributes, attribute values, and other related code. (For details, refer to the comment in the source document header.) This allows these markup constructs to be specially highlighted, using CSS, during presentation (including their status and requirement level) so they may be more easily recognized.

Since the normative edition of this specification may be rendered with different CSS style sheets, converted into other formats, rendered on visually limited hardware, or presented with text-to-speech engines, some or all of this highlighting may be lost. Care has been taken to assure that, in the absence of highlighting, every mention of these markup constructs will be clear and unambiguous.

In the above tables, there are four requirement levels:

1. “Required” means the element/attribute must appear, in some capacity, in all Binder documents.

2. “Conditionally Required” means the element/attribute must appear under certain element usage situations, and is optional in other situations.

3. “Optional” means the element/attribute is optional under all situations.

4. “Fixed” (applicable only to attributes) means the attribute is fixed to a certain value in the DTD and there is no separate requirement the attribute must appear in the associated element.

Similarly, there are three status levels:

1. “Normal” means the element/attribute has normal status in this specification.

2. “Deprecated” means the element/attribute has been deprecated, and support for it may be removed in a future version of this specification.

3. “Removed” means the element/attribute is no longer supported in this specification, but is nevertheless mentioned.

An empty cell in the tables means there is no mention in this specification of an element/attribute having the associated status and requirement level.

Attribute values are highlighted as en-US.

Other types of “code” are highlighted as PCDATA.

3.3.1 Important XML Markup Requirements

As specified in Section 3.1, all Basic Content Documents must be conforming XML 1.0 documents, which means, for example, they are well-formed. Following is a list of several specific XML markup requirements, but this list is by no means exhaustive. These requirements are mentioned since, when not followed, they contribute to a large fraction of encountered XML well-formedness and validation errors.

• Element and attribute names are case-sensitive. For example <div> and <DIV> are different elements.

• Attribute values must be enclosed in either single or double straight quotes. For example, class="abcd" and class='abcd' are conforming, but class=abcd, class="abcd' and class='abcd" are not.

• All non-empty elements must have properly formed starting and closing tags.

• All declared empty elements must be properly formed (see Section 3.3.5).

• All elements must properly nest.

• Depending upon the circumstance, certain markup characters, when used literally (e.g. & and <), must be escaped. Refer to the next Section 3.3.2 for details.

3.3.2 Character Entity and Numeric Character References

For XML 1.0 documents (and this includes Basic Content Documents), each individual character within character data is represented in one of two ways:

1. directly in the document’s text encoding, and

2. indirectly using a numeric character reference, or by a predefined or declared character entity reference which points to a numeric character reference.

For example, it is convenient to use numeric character references and allowed character entity references when the tool used to create an XML document is limited to ASCII encoding (UTF-8 conformant but limited to the Basic Latin script), and some characters fall outside of the ASCII range.

In certain circumstances, five of the characters used to define XML markup constructs (specifically & < > " and '), when used literally, must be represented (or “escaped”) by their numeric character references, or by their declared character entity reference equivalents. For this purpose, XML predefines entity references for these five characters which all XML processors must recognize:

Listed below are the circumstances when the five markup characters, used literally and not as part of markup, must be escaped:

1. The & and < characters, except when used within CDATA sections and Comments.

2. The " and ' characters when they appear within an attribute value and match the attribute value delimiting quote mark. It is recommended that both always be escaped in attribute values.

3. The > character in the very rare instance it appears in the string “]]>” when that string is not marking the end of a CDATA section. It is considered good practice to escape the > character wherever it is used literally.

Example of content document markup with both required and optional numeric and character entity references:

<h2 title='Jane&apos;s AT&amp;T R&#x00E9;sum&#x00E9;'>Jane's AT&amp;T R&#x00E9;sum&#x00E9;</h2>

A user agent will render the above markup as:

Jane's AT&T Résumé

3.3.3 CDATA Sections

CDATA sections may be used in XML documents (which includes Basic Content Documents) to escape blocks of text containing markup characters (e.g. “<” and “&”) when used literally. This is an alternative to individually escaping each markup character (see Section 3.3.2).

A CDATA section starts with “<![CDATA[” and terminates with “]]>”.

CDATA sections may be used anywhere character data may occur, except that they must not appear within an attribute value. They must not nest; the text content within a CDATA section must not contain the literal character sequence “]]>”.

Example:

<p>Insert the following in your document: &lt;h1&gt;Greetings!&lt;/h1&gt;</p>

is equivalent to

<p>Insert the following in your document: <![CDATA[<h1>Greetings!</h1>]]></p>

A user agent will render both of the above as:

Insert the following in your document: <h1>Greetings!</h1>

3.3.4 Comments

Comments may appear anywhere in an XML document (including a Basic Content Document) except before the XML declaration and within other markup. Comments are not part of the character data; they are primarily intended for content document authors to insert private commentary (notes) within the document.

A comment starts with “<!--” and terminates with “-->”; the comment text is between these two delimiters. The comment text must not contain the string “--” (two hyphens), but otherwise may include, without escaping, all the Unicode characters recognized in XML 1.0, including the XML markup characters. A comment must not terminate with the literal string “--->”.

Examples:

<!-- This is a comment -->

<p>XML markup characters</p> <!-- & < > " ' -->

To conform to this specification, user agents must not:

1. render the contents of comments,
2. execute any script or code (such as JavaScript) contained in comments,
3. take any action based on the content in comments.

3.3.5 Empty Elements and Empty Content

Some elements in a DTD may be declared EMPTY. When used in an XML document, these elements must not contain any content and must use the empty-element syntax (also known as “minimized form”) as specified in XML 1.0.

Example of correct usage of declared empty element syntax (the element img is declared EMPTY in this specification):

<img src="myimage.png" alt="A cool image"/>

Note: a sequence of one or more white space characters may appear before the closing “/” in empty-element syntax.

In this specification, the empty-element syntax must only be used for declared empty elements; it must not be used for declared non-empty elements when they contain no content.

Example of correct and incorrect usage when a declared non-empty element contains no content (the element p is declared non-empty in this specification):

<p/>      <!-- not allowed! -->
<p></p>   <!-- correct usage -->

When declared non-empty elements contain no content, or only a sequence of one or more white space characters, this occurence is referred in this specification as “empty content.”

3.3.6 White Space Handling

White space characters and their handling by user agents is an important consideration to both Basic Content Document authors and user agent developers.

In XML, the white space characters are:

• space ( )

• tab (	)

• carriage return (
)

• line feed (
)

The rules for white space handling of both character data and attribute values by XML processors are addressed in Sections 2.10, 3.2.1 and 3.3.3 of the XML 1.0 Specification.

User agent requirements:

1. For character data, XML processors are required to pass to the user agent all characters in a document that are not markup. This includes white space characters.

   Except where the XML attribute xml:space is specifically set to the value of preserve, or a similar override mechanism is applied (e.g., the CSS white-space property), in this specification user agents must normalize the character data of an element as follows:

   • Replace all sequences of two or more white space characters with a single space character ( ), and

   • Remove all leading and trailing spaces.

   Example:

   <p>
      <i> This
      </i>    is a
              paragraph.
   </p>
   

   and

   <p> <i> This    </i>   is   a paragraph. </p>
   

   are both equivalent to:

   <p><i>This</i> is a paragraph.</p>
   

2. For white space in attribute values, XML requires that all XML processors normalize attribute values before sending the attribute value data to the user agent. Note that this normalization process treats attribute values not of type CDATA differently from those of type CDATA.

   To conform to this specification, user agents must normalize CDATA attribute values as if they were not of type CDATA. That is, for attribute values of type CDATA, user agents must replace a sequence of space ( ) characters with a single space ( ) character, and remove any leading and trailing space ( ) characters.

   Example (the title attribute is of datatype CDATA):

   <p title=" This is   a
   
       paragraph ">This is a paragraph.</p>
   

   is equivalent to:

   <p title="This is a paragraph">This is a paragraph.</p>
   

3.3.7 Unicode Space Characters and Related Topics

Basic Content Document authors are free to use all the Unicode characters in character data, except those disallowed by XML and this specification (refer to "Unicode in XML and other Markup Languages" for recommendations on the Unicode characters not suitable for use in XML, and related topics.) This flexibility allows for the richest content in Basic Content Documents, meeting nearly all international needs, but in certain situations will create a few complexities for Basic Content Document authors and user agent developers.

One of the more complex topics concerns the spacing characters used for inter-word separation. Because the concept of a “word” in most languages plays a fundamental role in various word-related operations, such as text searching, line breaking, etc., Basic Content Document authors and user agent developers need to understand how the Unicode space characters are used to enable inter-word separation, plus the related topics of line breaking (primarily for the purpose of visual presentation), and soft hyphens.

<p>A content document author may insert a soft hy&shy;phen within a word.</p>

A content document author may insert a soft
hyphen within a word.

A content document author may insert a soft hy-
phen within a word.

4.1.1 Common Attribute Set

The Basic Content Document vocabulary, following XHTML 1.1, defines four [Common] attributes that may be applied to most elements. They are class, id, title, and xml:lang.

Because of their general importance, they are described in detail in this section. Two of the attribute descriptions, for class and id, specify constraints beyond what XHTML 1.1 allows.

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US">
...
<p>On June 26, 1963, in West Berlin, President John F. Kennedy
uttered the now-famous phrase: <span xml:lang="de-DE">Ich bin
ein Berliner.</span></p>
...
</html>

4.1.2 Supported Elements and Attributes

The table in this section lists (in alphabetical order by element) all the supported XHTML 1.1 elements and attributes in the Basic Content Document vocabulary. This table is non-normative — the Basic Content Document DTD, Version 1.0, is the normative vocabulary reference with respect to:

• allowed elements, attributes and attribute values, and

• element content model.

Each element in the “Element” column is linked to the corresponding general description in the HTML 4.01 specification, which provides a good overview of the purpose and use of the element and associated attributes. (As of the date of this specification, the XHTML specifications still refer to HTML 4.01 for descriptive details on elements and attributes.) The “May Contain” column summarizes the children elements and/or PCDATA (“parsed character data”) each element may, and in a few cases must, contain (i.e., a content model summary.) Within the “Supported Attributes” column, [Common] refers to the four common attributes described in Section 4.1.1. Other links in the table address particular constraints and requirements.

Document authors should find this table, and the many links it provides, a useful resource.

4.1.3 “Mnemonic” Character Entity References

The Basic Content Document DTD declares the 253 character entity references specified in the Character Entity References Common Set Specification, Version 1.0. These character entity references are identical to those supported in XHTML 1.1 (which, in turn, are inherited from HTML 4.01.) They include the five XML predefined character entity references (see Section 3.3.2.)

Basic Content Document authors may use these “mnemonic” character entities instead of the equivalent numeric character references, as explained in Section 3.3.2. User agents must recognize these character entities.

Example using numeric character references:

<h2>Jane&#x2019;s AT&#x0026;T R&#x00E9;sum&#x00E9;</h2>

The same example using “mnemonic” character entity references:

<h2>Jane&rsquo;s AT&amp;T R&eacute;sum&eacute;</h2>

Both the above examples will render as:

Jane’s AT&T Résumé

Future versions of this and related content document specifications may support an expanded common set of “mnemonic” character entity references derived from other document markup vocabularies such as TEI and DocBook.

4.2.1 a Element (deprecated)

The deprecated a element must not contain another a to any depth of nesting. This restriction is inherited from XHTML 1.0 Element Prohibitions, and cannot be enforced by a DTD.

Note: The a element is deprecated since support for it might be removed in a future version of this specification. Should support for a be removed in the future, its functionality will be replaced by another mechanism, such as one based on XLink, and/or based on XHTML 2.0 when it becomes a W3C Recommendation. Content document authors should certainly use the a element when needed — this is simply an advisory message to content document authors and developers as to possible future developments.

4.2.2 br Element (deprecated)

The br element is deprecated in this specification, and will likely be removed in a future version. XHTML 2.0 is planning to remove this element from its vocabulary, to be replaced by the Inline (i.e., text level) l element, which represents a semantic line of text within a block of text, such as a paragraph.

Content document authors should avoid using the br element whenever possible.

[Informative Commentary] In many situations content document authors can avoid using the deprecated br element by properly marking up the underlying document structure; the class attribute may be used for such “fine tuning.” A well-known problem from web page authoring with the br element is that many authors use it to “force” a desired visual presentation, thereby working against the reflowability and adaptability of the content to various hardware, applications and end-user presentation settings.

(Also refer to Section 4.2.8 on empty element syntax.)

4.2.3 “Mixed Flow” Elements (dd, div, li, td, th)

In XHTML 1.1, the DTD content model for each of the five elements dd, div, li, td, and th is “mixed flow”, meaning that an instance may simultaneously contain text (PCDATA), Inline elements and Block elements in any arbitrary order. Unfortunately, the XML 1.0 specification provides no mechanism to allow DTDs to further constrain such “mixed flow” content models.

It is generally considered very poor practice to randomly mix Block elements with PCDATA/Inline elements, and sometimes leads to ambiguities as to how user agents are to render such “mixed flow” markup. Thus, for conformance to this specification, every instance of use of these five elements must either contain (as children) only Block level elements, or contain only PCDATA/Inline elements.

Furthermore, it is recommended that these elements (excluding div) contain only Block level elements (thus having a content model similar to blockquote.) A future version of this specification may elevate this recommendation to a requirement.

Examples of permitted usage:

<-- PCDATA/Inline usage -->
<ul>
   <li>Here is a <em>list</em> item.</li>
</ul>

<-- Block level usage (recommended for <dd>, <li>, <td> and <th>) -->
<ul>
   <li>
      <p>Here is the <em>first paragraph</em> in a list item.</p>
      <p>Here is the <em>second paragraph</em> in a list item.</p>
   </li>
   ...
   <li><div>Here is a <em>different</em> list item.</div></li>
</ul>

Example of not permitted usage containing mixed Block, Inline and PCDATA:

<!-- Mixed usage not permitted in this specification -->
<ul>
   <li>
      <p>Here is the <em>first paragraph</em> in a list item.</p>
         Here is some <em>random</em> text placed in-between.
      <p>Here is the <em>second paragraph</em> in a list item.</p>
   </li>
</ul>

4.2.4 html Element

As noted in Section 3.1, for the required root element html, the attributes xmlns and xml:lang (for specifying the primary language of the Basic Content Document) are both required. In addition, the attribute xmlns must have the value “http://www.w3.org/1999/xhtml”.

Example where the primary language of the document is U.S. English:

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

For further information on xml:lang, refer to Section 4.1.1.4.

4.2.5 img Element (deprecated)

The deprecated inline element img is used to embed graphics images in Basic Content Documents. It must not be used to embed multimedia such as audio and video.

The required IRI attribute, src, is used to reference the image resource.

For improved accessibility, the required alt attribute should contain a brief and informative textual description of the image (for datatype information see Section 4.2.10.) This text is an acceptable fallback when the user agent cannot, for whatever reason, properly display the image — or for non-visual presentation such as text-to-speech.

Content document authors should include the title attribute in img, and its value may be the same as that used for the required alt attribute. If the title attribute is not present, user agents should assign it, giving it the value found in the alt attribute. (For more information on the title attribute, and recommended user agent processing of this attribute, refer to Section 4.1.1.3.)

Note: The img element is deprecated since support for it might be removed in a future version of this specification. Should support for img be removed in the future, its functionality will be replaced by another mechanism, such as one based on XLink, and/or based on XHTML 2.0 when it becomes a W3C Recommendation. Content document authors should certainly use the img element when needed — this is simply an advisory message to content document authors and developers as to possible future developments.

(Also refer to Section 4.2.8 on empty element syntax.)

4.2.6 pre Element

The pre element must not contain the elements img, sub, or sup to any depth of nesting. This restriction is inherited from XHTML 1.0 Element Prohibitions, and cannot be enforced by a DTD.

The attribute xml:space is FIXED. If this attribute is used, it must have the value “preserve”.

4.2.7 Header Elements: head, title, and meta

The Basic Content Document header section, defined by the required head element, is used to include metadata about the Basic Content Document. Despite the requirement for a header section in a Basic Content Document (necessary for XHTML 1.1 and OEBPS 1.2 conformance), user agents are not required to use any of the header metadata information.

The head element must contain exactly one title element, and may include any number of meta elements. The meta elements, if present, must follow the title element.

Like head, the title element is required for conformance with XHTML 1.1 and OEBPS 1.2. Its purpose is to contain a descriptive title of the Basic Content Document itself. It should not be used to specify the title for the publication of which the content document is a component.

The optional meta empty element may be used to specify additional metadata about the Basic Content Document. Like title, the meta element should not be used to specify metadata for the publication of which the content document is a component.

Each use of the meta element must conform to one of the following:

1. Dublin Core recommendations for embedding metadata in XHTML 1.1. Example:

   <meta name="DC.title" content="Chapter One" />
   

2. The value of the required name attribute starts with “x-” for any metadata system other than the aforementioned Dublin Core system, such as a “homegrown” system devised by the content document author. Example:

   <meta name="x-markuptechnician" content="John Doe"/>
   

For the meta element, the content attribute is required. Its value is of datatype CDATA (see Section 4.2.10 for allowed characters.) The required name attribute must follow the same character restrictions given for the value of the class common attribute (see Section 4.1.1.1.)

User agents are not required to use the metadata information in the meta empty element.

(Refer to Section 4.2.8 on empty element syntax for the meta element.)

4.2.8 Empty Elements: area, br, col, hr, img, and meta

The elements area, br, col, hr, img, and meta are declared empty in the Basic Content Document DTD. These elements must not contain any content and must use the empty-element syntax (also known as “minimized form”) for declared empty elements as specified in XML 1.0. (Also refer to Section 3.3.5 in this specification.)

Note: In using the empty-element syntax, when compatibility with HTML 4 is desired, content document authors should include at least one space before the terminal “/”.

Examples of correct usage of declared empty element syntax:

<hr/>
<hr />
<img src="myimage.png" alt="A cool image" />
<meta name="x-markuptechnician" content="John Doe"/>

4.2.9 Empty Content

When non-empty elements (elements which may contain content), contain no content or only a sequence of one or more white space characters, this occurence is referred to as “empty content.” (For more information, refer to Section 3.3.5 in this specification.)

Examples of empty content:

<p></p>
<p>   </p>
<li></li>
<td> </td>
<span class="pagemarker" id="page121" title="Page 121"></span>

In this specification, the empty-element syntax (see Sections 3.3.5 and 4.2.8) must not be used for empty content. For example:

<p/>       <!-- not allowed! -->
<p></p>    <!-- correct usage -->

How empty content is visually presented by user agents largely depends upon the style language rules and settings.

For example, in CSS 2.1, empty content table cells (td and th) and list items (li) automatically generate the appropriate placeholder boxes — they are significant content-wise even when empty. (It is not uncommon for a table to intentionally have one or more empty cells.)

With typical default CSS 2.1 style sheet settings, empty content Block and Inline elements (such as p and span) will visually collapse to nothing. Unlike table cells and list items, they are not considered significant content-wise, but may serve non-content purposes such as for linking and the placing of special “mile markers” within the markup of the content document (see the span example above.)

Content authors should not use empty content Block and Inline elements solely for the purpose of forcing a particular visual presentation.

4.2.10 Attributes of Datatype CDATA (Text): abbr, alt, content, scheme, summary, title

Six attributes (abbr, alt, content, scheme, summary and title) are of datatype CDATA.

The allowed Unicode character range for attribute values of datatype CDATA is given in XML 1.0, with the following constraints:

1. The literal < character must not appear. If this character is to be used literally, it must be escaped.

2. The literal & character must not appear except as part of a predefined or declared character entity reference. If this character is to be used literally (not part of an entity reference), it must be escaped.

3. The literal " and ' characters must not appear when they match the attribute delimiter quote marks; they must be escaped. It is recommended that both of these characters always be escaped when they appear in attribute values.

Three of these attributes are further described elsewhere:

• alt attribute for the img element: Section 4.2.5.

• title common attribute: Section 4.1.1.3.

• content attribute for the meta element: Section 4.2.7.

4.2.11 Attributes With IRI References (cite, href, src)

Three attributes (cite, href and src) reference resources using IRI values (Internationalized Resource Identifiers, RFC 3987). IRI and URI (RFC 3986) are similar (a URI is an IRI), but IRI is designed to support nearly all of the Unicode character set beyond Basic Latin without the need for (essentially unreadable and wasteful) percent-encoded octets.

Note: This specification does not define the allowed IRI schemes. The allowed schemes, and usage details, are to be defined by publication frameworks which reference this specification.

The src attribute for the img element is further described in Section 4.2.5.