XML Character Entities

The character entity sets defined by this Standard are summarized in Appendix A through Appendix S.

In order to use these entities in a document, they must be declared. Entities can be declared in the external subset or the internal subset, as described in [XML]. An example document, with the declaration in the internal subset, is shown in Example 1.

<!DOCTYPE doc [
<!ENTITY % iso-lat1 PUBLIC "ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
                    "http://www.oasis-open.org/docbook/xmlcharent/0.3/iso-lat1.ent">
%iso-lat1;
]>
<doc>
<p>This document declares the ISO Latin 1 Character Entity Set, providing
access to the ISO Latin 1 entities, such as "&eacute;" and "&copy;".</p>
</doc>

Named XML entities (except for the five predefined entities) cannot be used if they are not declared. Entity declaration requires either an external or an internal subset. Some classes of applications forbid the occurrence of markup declarations in documents. For these documents, named character entities are inaccessible.

In this section, we introduce an XML vocabulary with the semantics of character entity reference. This Standard defines the semantics of elements and attributes declared in the "http://www.oasis-open.org/docbook/xmlcharent/names" namespace.

This namespace contains exactly one element, char. The char element has two attributes, entity and name. They are mutually exclusive.

The entity attribute identifies characters by their character entity names. (The set of valid names is the closed set of names associated with character entity sets defined by this Standard.) Case is significant in entity names.

The name attribute identifies characters by their Unicode character names. (The set of valid names is the set of character names published in the [Unicode] specification, or any later version of that specification.) Case is insignificant in character names.

The [RELAX NG] definition of this namespace is shown in figure Figure 1.

<?xml version="1.0"?>
<grammar xmlns="http://relaxng.org/ns/structure/0.9"
         ns="http://www.oasis-open.org/docbook/xmlcharent/names">

<start>
  <element name="char">
    <choice>
      <attribute name="entity">
        <ref name="EntityNames"/>
      </attribute>
      <attribute name="name">
        <ref name="UnicodeNames"/>
      </attribute>
    </choice>
  </element>
</start>

<define name="EntityNames">
  <!-- Logically, this is the list of ISO 9573 Character Entity Names -->
  <!-- For now, just text. -->
  <text/>
</define>

<define name="UnicodeNames">
  <!-- Logically, this is the list of Unicode Character Names -->
  <!-- For now, just text. -->
  <text/>
</define>

</grammar>

Example 2 shows a sample document using this mechanism.

<doc xmlns:e="http://www.oasis-open.org/docbook/xmlcharent/names">
<p>This document uses the character names element to access
character entities, such as "<e:char name="eacute"/>" and
"<e:char name="COPYRIGHT SIGN"/>".</p>
</doc>

The character names element is limited to contexts where elements may occur. In particular, elements may not occur in XML attribute values. Note, however, that internationalization requirements such as bidirectional language support and Ruby already require structure in arbitrary contexts. It is probably an error to use attributes for human-readable content.