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. |