This section explains many of the features of XML, but not all, and some -features not in detail. For a complete description, see the XML -specification.
The DTD contains various declarations; in general you can only use a feature if -you have previously declared it. The document instance file may contain the -full DTD, but it is also possible to split the DTD into an internal and an -external subset. A document must begin as follows if the full DTD is included: - -
<?xml version="1.0" encoding="Your encoding"?> -<!DOCTYPE root [ - Declarations -]>- -These declarations are called the internal subset. Note -that the usage of entities and conditional sections is restricted within the -internal subset.
If the declarations are located in a different file, you can refer to this file -as follows: - -
<?xml version="1.0" encoding="Your encoding"?> -<!DOCTYPE root SYSTEM "file name">- -The declarations in the file are called the external -subset. The file name is called the system -identifier. -It is also possible to refer to the file by a so-called -public identifier, but most XML applications won't use -this feature.
You can also specify both internal and external subsets. In this case, the -declarations of both subsets are mixed, and if there are conflicts, the -declaration of the internal subset overrides those of the external subset with -the same name. This looks as follows: - -
<?xml version="1.0" encoding="Your encoding"?> -<!DOCTYPE root SYSTEM "file name" [ - Declarations -]>
The XML declaration (the string beginning with <?xml and -ending at ?>) should specify the encoding of the -file. Common values are UTF-8, and the ISO-8859 series of character sets. Note -that every file parsed by the XML processor can begin with an XML declaration -and that every file may have its own encoding.
The name of the root element must be mentioned directly after the -DOCTYPE string. This means that a full document instance -looks like - -
<?xml version="1.0" encoding="Your encoding"?> -<!DOCTYPE root SYSTEM "file name" [ - Declarations -]> - -<root> - inner contents -</root>
Some characters are generally reserved to indicate markup such that they cannot -be used for character data. These characters are <, >, and -&. Furthermore, single and double quotes are sometimes reserved. If you -want to include such a character as character, write it as follows: - -
< instead of <
> instead of >
& instead of &
' instead of '
" instead of "
&#n;- -where n is the decimal number of the -character. Alternatively, you can specify the character by its hexadecimal -number: - -
&#xn;- -In the scope of declarations, the character % is no longer free. To include it -as character, you must use the notations % or -%.
Note that besides <, >, &, -', and " there are no predefines character entities. This is -different from HTML which defines a list of characters that can be referenced -by name (e.g. ä for รค); however, if you prefer named characters, you -can declare such entities yourself (see below).
Elements structure the document instance in a hierarchical way. There is a -top-level element, the root element, which contains a -sequence of inner elements and character sections. The inner elements are -structured in the same way. Every element has an element -type. The beginning of the element is indicated by a start -tag, written - -
<element-type>- -and the element continues until the corresponding end tag -is reached: - -
</element-type>- -In XML, it is not allowed to omit start or end tags, even if the DTD would -permit this. Note that there are no special rules how to interpret spaces or -newlines near start or end tags; all spaces and newlines count.
Every element type must be declared before it can be used. The declaration -consists of two parts: the ELEMENT declaration describes the content model, -i.e. which inner elements are allowed; the ATTLIST declaration describes the -attributes of the element.
An element can simply allow everything as content. This is written: - -
<!ELEMENT name ANY>- -On the opposite, an element can be forced to be empty; declared by: - -
<!ELEMENT name EMPTY>- -Note that there is an abbreviated notation for empty element instances: -<name/>.
There are two more sophisticated forms of declarations: so-called -mixed declarations, and regular -expressions. An element with mixed content contains character data -interspersed with inner elements, and the set of allowed inner elements can be -specified. In contrast to this, a regular expression declaration does not allow -character data, but the inner elements can be described by the more powerful -means of regular expressions.
A declaration for mixed content looks as follows: - -
<!ELEMENT name (#PCDATA | element1 | ... | elementn )*>- -or if you do not want to allow any inner element, simply - -
<!ELEMENT name (#PCDATA)>
Example
If element type q is declared as - -
<!ELEMENT q (#PCDATA | r | s)*>- -this is a legal instance: - -<q>This is character data<r></r>with <s></s>inner elements</q>- -But this is illegal because t has not been enumerated in the -declaration: - -<q>This is character data<r></r>with <t></t>inner elements</q>
The other form uses a regular expression to describe the possible contents: - -
<!ELEMENT name regexp>- -The following well-known regexp operators are allowed: - -
element-name
(subexpr1 , ... , subexprn )
(subexpr1 | ... | subexprn )
subexpr*
subexpr+
subexpr?
The exact syntax of the regular expressions is rather strange. This can be -explained best by a list of constraints: - -
The outermost expression must not be -element-name.
Illegal: -<!ELEMENT x y>; this must be written as -<!ELEMENT x (y)>.
For the unary operators subexpr*, -subexpr+, and -subexpr?, the -subexpr must not be again an -unary operator.
Illegal: -<!ELEMENT x y**>; this must be written as -<!ELEMENT x (y*)*>.
Between ) and one of the unary operatory -*, +, or ?, there must -not be whitespace.
Illegal: -<!ELEMENT x (y|z) *>; this must be written as -<!ELEMENT x (y|z)*>.
There is the additional constraint that the -right parenthsis must be contained in the same entity as the left parenthesis; -see the section about parsed entities below.
Note that there is another restriction on regular expressions which must be -deterministic. This means that the parser must be able to see by looking at the -next token which alternative is actually used, or whether the repetition -stops. The reason for this is simply compatability with SGML (there is no -intrinsic reason for this rule; XML can live without this restriction).
Example
The elements are declared as follows: - -
<!ELEMENT q (r?, (s | t)+)> -<!ELEMENT r (#PCDATA)> -<!ELEMENT s EMPTY> -<!ELEMENT t (q | r)>- -This is a legal instance: - -<q><r>Some characters</r><s/></q>- -(Note: <s/> is an abbreviation for -<s></s>.) - -It would be illegal to leave <s/> out because at -least one instance of s or t must be -present. It would be illegal, too, if characters existed outside the -r element; the only exception is white space. -- This is -legal, too: - -<q><s/><t><q><s/></q></t></q>
Elements may have attributes. These are put into the start tag of an element as -follows: - -
<element-name attribute1="value1" ... attributen="valuen">- -Instead of -"valuek" -it is also possible to use single quotes as in -'valuek'. -Note that you cannot use double quotes literally within the value of the -attribute if double quotes are the delimiters; the same applies to single -quotes. You can generally not use < and & as characters in attribute -values. It is possible to include the paraphrases <, >, -&, ', and " (and any other reference to a general -entity as long as the entity is not defined by an external file) as well as -&#n;.
Before you can use an attribute you must declare it. An ATTLIST declaration -looks as follows: - -
<!ATTLIST element-name - attribute-name attribute-type attribute-default - ... - attribute-name attribute-type attribute-default ->- -There are a lot of types, but most important are: - -
CDATA: Every string is allowed as attribute value.
NMTOKEN: Every nametoken is allowed as attribute -value. Nametokens consist (mainly) of letters, digits, ., :, -, _ in arbitrary -order.
NMTOKENS: A space-separated list of nametokens is allowed as -attribute value.
#REQUIRED: The attribute must be specified.
#IMPLIED: The attribute can be specified but also can be -left out. The application can find out whether the attribute was present or -not.
"value" or -'value': This particular value is -used as default if the attribute is omitted in the element.
Example
This is a valid attribute declaration for element type r: - -
<!ATTLIST r - x CDATA #REQUIRED - y NMTOKEN #IMPLIED - z NMTOKENS "one two three">- -This means that x is a required attribute that cannot be -left out, while y and z are optional. The -XML parser indicates the application whether y is present or -not, but if z is missing the default value -"one two three" is returned automatically.This is a valid example of these attributes: - -
<r x="He said: "I don't like quotes!"" y='1'>
Elements describe the logical structure of the document, while -entities determine the physical structure. Entities are -the pieces of text the parser operates on, mostly files and macros. Entities -may be parsed in which case the parser reads the text and -interprets it as XML markup, or unparsed which simply -means that the data of the entity has a foreign format (e.g. a GIF icon).
If the parsed entity is going to be used as part of the DTD, it -is called a parameter entity. You can declare a parameter -entity with a fixed text as content by: - -
<!ENTITY % name "value">- -Within the DTD, you can refer to this entity, i.e. read -the text of the entity, by: - -
%name;- -Such entities behave like macros, i.e. when they are referred to, the -macro text is inserted and read instead of the original text. - -
- -If the contents of the entity are given as string constant, the entity is -called an internal entity. It is also possible to name a -file to be used as content (an external entity): - -Example
For example, you can declare two elements with the same content model by: - -
<!ENTITY % model "a | b | c"> -<!ELEMENT x (%model;)> -<!ELEMENT y (%model;)>
<!ENTITY % name SYSTEM "file name">- -There are some restrictions for parameter entities: - -
If the internal parameter entity contains the first token of a declaration -(i.e. <!), it must also contain the last token of the -declaration, i.e. the >. This means that the entity -either contains a whole number of complete declarations, or some text from the -middle of one declaration.
Illegal: -
<!ENTITY % e "(a | b | c)>"> -<!ELEMENT x %e;Because <! is contained in the main -entity, and the corresponding > is contained in the -entity e.
If the internal parameter entity contains a left paranthesis, it must also -contain the corresponding right paranthesis.
Illegal: -
<!ENTITY % e "(a | b | c"> -<!ELEMENT x %e;)>Because ( is contained in the entity -e, and the corresponding ) is -contained in the main entity.
When reading text from an entity, the parser automatically inserts one space -character before the entity text and one space character after the entity -text. However, this rule is not applied within the definition of another -entity.
Legal: -
-<!ENTITY % suffix "gif"> -<!ENTITY iconfile 'icon.%suffix;'>Because %suffix; is referenced within -the definition text for iconfile, no additional spaces are -added.
Illegal: -
<!ENTITY % suffix "test"> -<!ELEMENT x.%suffix; ANY>-Because %suffix; is referenced outside the definition -text of another entity, the parser replaces %suffix; by -spacetestspace.
Illegal: -
<!ENTITY % e "(a | b | c)"> -<!ELEMENT x %e;*>Because there is a whitespace between ) -and *, which is illegal.
An external parameter entity must always consist of a whole number of complete -declarations.
In the internal subset of the DTD, a reference to a parameter entity (internal -or external) is only allowed at positions where a new declaration can start.
If the parsed entity is going to be used in the document instance, it is called -a general entity. Such entities can be used as -abbreviations for frequent phrases, or to include external files. Internal -general entities are declared as follows: - -
<!ENTITY name "value">- -External general entities are declared this way: - -
<!ENTITY name SYSTEM "file name">- -References to general entities are written as: - -
&name;- -The main difference between parameter and general entities is that the former -are only recognized in the DTD and that the latter are only recognized in the -document instance. As the DTD is parsed before the document, the parameter -entities are expanded first; for example it is possible to use the content of a -parameter entity as the name of a general entity: -&%name;;[1].
General entities must respect the element hierarchy. This means that there must -be an end tag for every start tag in the entity value, and that end tags -without corresponding start tags are not allowed.
Example
If the author of a document changes sometimes, it is worthwhile to set up a -general entity containing the names of the authors. If the author changes, you -need only to change the definition of the entity, and do not need to check all -occurrences of authors' names: - -
<!ENTITY authors "Gerd Stolpmann">- -In the document text, you can now refer to the author names by writing -&authors;.Illegal: -The following two entities are illegal because the elements in the definition -do not nest properly: - -
<!ENTITY lengthy-tag "<section textcolor='white' background='graphic'>"> -<!ENTITY nonsense "<a></b>">
Earlier in this introduction we explained that there are substitutes for -reserved characters: <, >, &, ', and -". These are simply predefined general entities; note that they are -the only predefined entities. It is allowed to define these entities again -as long as the meaning is unchanged.
Unparsed entities have a foreign format and can thus not be read by the XML -parser. Unparsed entities are always external. The format of an unparsed entity -must have been declared, such a format is called a -notation. The entity can then be declared by referring to -this notation. As unparsed entities do not contain XML text, it is not possible -to include them directly into the document; you can only declare attributes -such that names of unparsed entities are acceptable values.
As you can see, unparsed entities are too complicated in order to have any -purpose. It is almost always better to simply pass the name of the data file as -normal attribute value, and let the application recognize and process the -foreign format.
| [1] | This construct is only -allowed within the definition of another entity; otherwise extra spaces would -be added (as explained above). Such indirection is not recommended. Complete example: - <!ENTITY % variant "a"> <!-- or "b" --> -<!ENTITY text-a "This is text A."> -<!ENTITY text-b "This is text B."> -<!ENTITY text "&text-%variant;;">-You can now write &text; in the document instance, and -depending on the value of variant either -text-a or text-b is inserted. |