8
XML document types

Introduction

This chapter goes beyond the basic knowledge that you need in order to write an XHTML page, and if you wish you can give it a miss on first reading. We can in fact write XHTML documents, or HTML documents without understanding a thing about the underlying grammars that govern them. A large proportion of pages on the web today are written by authors who couldn't tell an ATTLIST declaration from an ENTITY declaration. However if we want to write good XHTML pages, and particularly if we want to exploit the power of modularization we should understand something about DTD's and validation. 

We had a brief look at XML in chapter 1. We in fact looked at what was meant by the term a "well-formed" document, and we looked briefly at the requirements of a well-formed document. We also talked about Document Type Definitions in XML, and in SGML, and how Document Type Definitions lay out the rules that a documents markup must take, what types of elements are allowed, what they may contain, and what attributes they may take. We can say that a DTD defines a 'class' of documents, and that every document written according to the rules of a particular DTD belongs to that 'class'. In other words a document written in XHTML is a member of the XHTML class of documents.

We could also use the language of object orientated programming. We could say that a given document is an 'object', and if written to the rules laid out in a certain DTD a document is an 'instance' of that class of document. 

In this chapter we will take a slightly broader look at well-formed documents, and then we will look at DTD's and Valid documents. We will look at the syntax of a DTD, and we will look at how to write one. We will in fact make up our own XML markup language called 'html-lite', which will contain some of the elements found in XHTML.

We will also look at how to validate a document using a validating parser. In fact we will build our own validating parser using the parser that comes with IE5.

We will finish of this chapter with a brief look at how we can modularize a DTD. In other words we can take a large DTD and break it up into smaller parts. This will be a prelude to the next chapter where we actually look at XHTML's modules.



What we will cover
* We will review the concept of well formedness, and what is necessary for a document to be well formed.

* We will look at what is meant by a valid document, and validation.

* We will build our own validator using the parser built into IE5.

* We will write our own DTD for a 'lite' version of XHTML


Well Formed XML Documents

We had a look at what constitutes a well-formed XML document in chapter 1.  Let's just review this now.

* There must be a root element that contains the whole document.

* All the elements must nest.

* All the elements must be of the correct form

* The element names must match the 'name production'.

* All the attributes must match the name production

* The attribute values must all be quoted

Let's examine this in a bit more detail

Root elements

There must be a root element that encloses the whole document. Note that this element can contain it self, a process know as recursion.

The following are legal XML documents

<doc>
      this is a legal XML document
 </doc>


<doc>
  <doc>
      this is a legal XML document
  </doc>
</doc>

This however is not

<doc>
      this is NOT a legal XML document
 </doc>
<doc>
      there is no enclosing root element
 </doc>

The tags and elements must be of the correct form
The rules governing the forms of tags and elements can be summed up as follows

* All tags must open with a 'less than' angle bracket, and close with a 'greater than' angle bracket.

* For every opening tag there must be a matching closing tag (except for empty elements).

* Empty elements must take a special form.

Tag delimiters

The general syntax for an opening tag is  <[element name]>.

The general syntax for a closing tag is  </[element name]>

Tags must match

Except for the special case of empty elements there MUST be a closing element, and the tag name must be the same. e.g.

<atag>...</atag>

XML is case sensitive so atag is not the same as Atag, or ATAG.

The following constructs are illegal

<atag>...</ATAG>

<Atag>....</atag>

Empty elements

Empty elements must take a special form

<[element name]/>

e.g.  in XHTML, <br/>and <hr/>

Note that for backward compatibility with old browsers it is recommended that one leave a space before the forward slash. E.g. <br /> <hr />. Leaving white space after the name (but not before) is legal XML.
Nesting
All the elements must nest. By this we mean that every element must be completely contained within another.

These elements nest

<a> <b> <c></c> </b> </a>

<a> <b></b> <c></c> </a>

These elements DO NOT nest

<a> <b><c> </b></c> </a>




Name productions

All the element and attribute names must match the so called XML "name production"

In order to match the name production, the name must begin with either a colon, a underscore, or a letter, and also must contain only alpha numeric characters, the underscore (_), a colon(:), a dash(-), or a period(.). 

The use of the colon however is reserved for the use of the W3C, so don't YOU use it!

There are numerous other non-latin characters that are also legal. This is out of scope for this book, but if you are writing in a non-latin tongue and not using the western alphabet, consult the XML recommendation.

Note the following are legal names

<first-name>
<_firstname>
<:first.name>

The following are not

<1stname>
< firstname> (space between angle bracket and f)
<first@name>

Attributes
Attributes must start with white space, and their names must follow the name production, they must be followed by an 'equals' sign, and then a quoted value.

The general syntax is

[white space][attribute name]='[quoted value]'

There must be no white space either side of the 'equals' sign

There can only be one attribute of the same name on any given element.
Attribute values must be quoted
The values of an attribute must be quoted with matching single '[att value]'or double "[att value]" quotes. 

The value of a value quoted with double quotes cannot contain the  ampersand (&) character, the less than (<) character or a double quote (") 

The value of a value quoted with single quotes cannot contain the  ampersand (&) character, the less than (<) character or a single quote (')

Prologs
All XML documents must have prolog, however the prolog can contain absolutely nothing!

When the prolog does contain content it can contain the following

* A Version declaration

* A document type declaration

* Comments

* Processing instructions

Version declarations
When a version type declaration is present it must be the first thing in the document. The syntax is very exact

<?xml version="1.0"?>

A version can also include an encoding declaration, but this is out of scope for this book.

There can be only one version declaration.

At present there is only one version of XML.

Document type declaration
We will be looking at document type declarations when we look at valid XML documents and DTD's. An XML document can only have one Document Type Declaration.
Processing Instructions
Processing instructions (PI) can occur anywhere in either the prolog, or the document. They take the general syntax

<?[target] white-space [data]?>

The target is the application at which the instruction is directed, and the data are the instructions. The user-agent must of course understand the processing instruction in order to implement it!

The only PI that is implemented at the moment is the processing instruction that connects an XML document to a style sheet. We saw this in chapter 1 but here it is again.

<?xml-stylesheet type="text/css" href="html-lite1.css"?>

Let's try linking a simple xml document with a 'lite' version of XHTML to a style sheet.

Try it out. Linking an 'html-lite' document to a style sheet.

Our html-lite document only has a few of xhtml's elements. Type up this well formed xml document. Save it as html-lite1.xml

<?xml version="1.0" ?>
<html-lite>
  <head>
    <title>HTML-lite example 1</title>
  </head>
  <body>
    <h1>HTML-lite example 1</h1>
    <p>This is a paragraph with some <em>emphasized</em> text.</p>
  </body>
</html-lite>

This is what you will see when you run it in IE5



What's going on

We have a well formed xml document not associated with any style sheet. The default behavior for IE5 is to display this document as a tree view.

Now let's add a reference to a style sheet. Add the following line to the document.

<?xml version="1.0" ?>
<?xml-stylesheet type="text/css" href="html-lite1.css"?>
<html-lite>
  <head>
    <title>HTML-lite example 1</title>
  </head>
  <body>
    <h1>HTML-lite example 1</h1>
    <p>This is a paragraph with some <em>emphasized</em> text.</p>
  </body>
</html-lite>

Note that we have not yet written a style sheet!

Run this again in IE5. This is what you will see.



What's going on
Here are the relevant parts of the processing instruction we have added.

* 'xml-stylesheet'. This is the target of the PI. It tells the user agent that we are dealing with an xml style sheet

* ' type="text/css" '. This tells the use agent the type of style sheet it is dealing with. It is a style sheet in text format written to the rules of CSS. This is part of the 'data' of the PI.

* 'href="html-lite1.css" '. This is also part of the data of the PI. It tells the user agent where to find the style sheet.

Because of the processing instruction the conforming user agent (IE5) knows that it is mean to display the document. In other words it is to discard the markup in the display and display it without the tags. However it can't find the style sheet because we have not yet written it. It therefore displays the content of the elements in its default display, which happens to be as an inline flow object with 12-point 'Times New Roman' font style (for my PC).


Let's now write a style sheet.

Try it out. Adding the style sheet.

Type this up and save it in the same folder as 'html-lite1.css'. Don't worry if you don't understand the details of the style sheet, it will be explained in chapter 11. However the syntax of CSS is almost intuitive!

Note however that we have set the display property of our head element to none, which means that none of its content, and this includes the child element 'title' will be displayed.

/*This is html-lite1.css*/
  head{    
     display:none; 
  } 
  body{
     display:block; 
     background-color:white;   
     font-size:12pt;
  }
  h1{
     display:block;
     font-size:24pt;
  }
  p{
     display:inline;
  }
  em{
     font-style:italic;
     display:inline;
  }
  pre{
     font-family:courier new,monospace;
     white-space:pre;
     display:block;
  }


now when we refresh our page we will see the following



What's going on

The user agent (IE5) now goes to the style sheet, looks up the appropriate style for each element, and then decorates the parse tree with the appropriate style.It then displays it. All this thanks to a processing instruction!
Comments
Comments are very important in any programming language. They are notes to ourselves, and other interested parties, explaining why we have done what we have done. They are particularly important when we write more than the most trivial DTD. At a minimum we should explain the rationale for every element we add and why we are seleting the attributes that we are selecting. 
In XML they take the form 

<!--[comment goes here]-->

Comments form part of the parse tree but are never displayed or interpreted. Because they form part of the parse tree it does mean that they can be manipulated using the DOM. See chapter ?
CDATA Sections
There will be occasions in our pages when we will not want our markup to be processed, we want to pass it right through the user agent and display it. If you ever get round to writing a book on XML or XHTML you will use this feature all the time!

To do this we wrap it in a CDATA section. CDATA stands for character data. A CDATA section tells the User Agent "Treat every character in this section as a character to be displayed, and not as markup".

The general syntax to create a CDATA section is

<![CDATA[  ..place text containing mark up here..]]>

The only thing you can't put in a CDATA section is ']]>' (For obvious reasons, otherwise when the parser saw it, it would end the CDATA section!)

Let's create a CDATA section now.

Try it out. Creating a CDATA section

Make the following alterations to html-lite1.xml, and save it as cdata1.xml

<?xml version="1.0" ?>
<!--a style sheet processing instruction-->
<?xml-stylesheet type="text/css" href="html-lite1.css"?>
<html-lite>
  <head>
    <title>HTML-lite example 1</title>
  </head>
<body>
  <h1>HTML-lite example 1</h1>
  <p>This is a paragraph with some <em>emphasized</em> text.</p>
  <p>Here is how the previous three flow objects were marked up</p>
  <pre>
  <![CDATA[
    <h1>HTML-lite example 1</h1>
    <p>This is a paragraph with some <em>emphasized</em> text.</p>]]>
  </pre>
</body>
</html-lite>

This is what you will see when you run it in IE5



What's going on

As you can see the entire markup that was enclosed in the CDATA section was not parsed but was passed on to the screen for display.

We placed this in 'pre' tags and asked the style sheet to preserve the white space, but unfortunately IE5 does not support this CSS property.

That's all we want to say about well-formed XML, so let's move on to look at Valid XML
Valid XML documents
A valid XML document is a document that is not only well-formed but conforms to the structure laid out in its Document Type Definition (DTD). The DTD is contained or referenced in the Document Type Declaration that is found in the prolog. Let's have a look at the document type declaration right now.

It is unfortunate that Document Type Definition, and Document Type Declaration share the same acronym, and are so similar, and this can cause much confusion to beginning authors. If you remember that the Declaration declares the document type, and also contains the definition, and the Definition Defines the document you are writing  you will be OK.

Document Type Declarations

As we saw earlier, a document type declaration is part of the prolog  of the document. It must come after the version declaration (if any), and before the root element.

We announce a document type declaration with the following syntax

<!DOCTYPE ..name of document, same as root element..[
	..DTD or reference to external DTD..
	..entity declarations..
]>

For a document with the root element called greeting .xml.

Note that the normal convention is to put variable names in square brackets, but here square brackets are part of the syntax so we have used  '..' instead.


In order to validate a document of any size you must either be a computing Genius, or have a validating parser. As few of us can lay claim to the first accolade, let's look at how we can build our own validating parser.

Making a Validating Parser

We can construct a Validating parser from the ActiveX control (MSXML.DLL) that comes with IE5. We have done this for you. You can either download the file as an HTML file from www.wrox.com. or copy it from the listing given in appendix ?  Just as you don't have to have any knowledge of programming to use an application, you don't have to have any knowledge of Scripting languages to use this html file as a parser. 

Using the Parser
The diagram below shows a screen shot of the parser in operation. Note the following points

* As the parser uses the IE5 DLL MSXML.DLL as an active X object it will only work in IE5 or better.

* You have the choice of parsing in the validating or Well-formed mode.

* You can choose to expand any external entities or not.

* Either browse for a file on your computer, or type in an URL

* The 'browse' function is designed to be run on your desktop. If you run it from the web and try and access a file on your own machine you will more than likely get an "Access denied" error message. 

* The result of the parsing operation is given in the text box. 



The above shot shows that the document greeting.xml has been successfully validated.
Document Type Definitions
The Document Type Definition sets out the rules of structure for any given XML document. A DTD will contain some or all of the following.

1. A listing of all the allowed element types in the document.

2. A listing of all the allowed content for any given element.

3. 1 and 2 are contained in a construct called the ELEMENT declaration

4. A listing of all the allowed attributes for an element.

5. A description of the attribute type and whether or not the attribute is required.

6. Optionally the default value for the attribute.

7. 4,5, and 6 are contained in the ATTLIST declaration

8. A declaration of all the entities in the document. These can be parameter entities or general entities.

9. A  declaration of all the Notations and their attributes

We will look at how these are declared and the syntax employed in the sections below.
 
First however lets have a look at where in the document we actually place our DTD. 
Internal and external DTD's

The DTD may either be contained in a separate document, or it may be embedded in the document type declaration. When the latter method is employed it is called an internal DTD, when the former is employed it is called an external DTD.

For anything other than the most trivial document we will be using an External DTD. This has several advantages, chief of which is that we can reference a single DTD from several documents.

Lets have a look at DTD, for our simplest well formed document, 'greeting .xml'.
Internal DTD's

Here is greeting.xml with an internal DTD that consists of a single element, and a single element declaration.

Try it out. Writing a simple Intrnal DTD

Type up the following, then run it through your parser to make sure it validates. If it doesn't validate, correct the errors (which will be Typo's I promise you!) and run it again. The screen shot above shows the results of running this document.

<?xml version="1.0" ?>
<!--internal document type definition for greeting-->
<!DOCTYPE greeting [
<!ELEMENT greeting (#PCDATA) >
]>

<greeting>Hello Valid XML!</greeting>


What's going on

First we have our version declaration, 

<?xml version="1.0" ?>

followed by a comment.

<!--internal document type definition for greeting-->


Now we have our document type declaration.

<!DOCTYPE greeting [
<!ELEMENT greeting (#PCDATA) >
]>

Note the syntax. We announce the beginning of our Declaration with the following statement. It MUST be in upper case.

<!DOCTYPE

Every thing between <!DOCTYPE, and the matching closing angle bracket > is the Document Type Declaration.

<!DOCTYPE is followed by white-space, then the name of the document. This is ALLWAYS the same as the root element. i.e in this case  greeting

In the case of the internal DTD we now put white space followed by an opening square bracket [

Every thing between the opening square bracket, and the closing square bracket ']' is the document type Definition. (DTD)

In this case it consists of a single element declaration

<!ELEMENT greeting (#PCDATA) >

We will look in more detail at element declarations shortly. For now just note the keyword that starts an element declaration <!ELEMENT, followed by white space, followed by the element name, followed by more white space, followed by the allowed content in parentheses. This is all closed off with a closing angle bracket.



External DTD's

To reference an external DTD in our file we start of with the same DOCTYPE declaration followed by the same document name, now though we omit the angled brackets and put SYSTEM. Note that it must be in upper case. This is followed by an URL that is enclosed in either single or double quotes, which references our DTD.

<?xml version="1.0" ?>
<!--internal document type definition for greeting-->
<!DOCTYPE greeting SYSTEM "greeting.dtd">

<greeting>Hello Valid XML!</greeting>


The DTD is contained in a separate file. Note that this file must contain nothing except comments and declarations.

<!--external document type definition for greeting.xml
this is greeting.dtd-->

<!DOCTYPE greeting [
<!ELEMENT greeting (#PCDATA) >

Now that we've seen where to put our DTD, lets jump right in and build a simple DTD for a 'lite' version of XHTML. We will start off with a simple  xml file and add to it as we go along.
Element declarations

We are going to define the allowed elements for our first pass at a document of the type 'html-lite'.

Here is the first version of a file of the document type 'html-lite'. We have a root element which contains a head and a body element which also have child elements. We have indented the children to make things clearer.

<?xml version="1.0" ?>
<html-lite>
  <head>
    <title>HTML-lite example 1</title>
  </head>
  <body>
    <h1>HTML-lite example 1</h1>
    <p>This is a paragraph with some <em>emphasized</em> text.</p>
  </body>
</html-lite>

Note in particular the structure of this document. The following diagram lays out the relationship of the elements one to the other.



We will declare each element in turn, and for each element we will declare the allowed content.

Try it out. Writing a DTD for html-lite1.xml

Here is the DTD for html-lite. Type it up and save it in the same folder as html-lite1.xml

<!ELEMENT html-lite (head,body) >
<!ELEMENT head (title) >
<!ELEMENT body (h1|p)* >
<!ELEMENT title (#PCDATA) >
<!ELEMENT h1 (#PCDATA) >
<!ELEMENT p (#PCDATA|em)* >
<!ELEMENT em (#PCDATA) >

Now make the following changes to 'html-lite1.xml' and save it as 'html-lite2.xml'

<?xml version="1.0" ?>
<!DOCTYPE html-lite SYSTEM "html-lite2.dtd">
<html-lite>
<head>
<title>HTML-lite example 1</title>
</head>
<body>
<h1>HTML-lite example 1</h1>
<p>This is a paragraph with some <em>emphasized</em> text.</p>
</body>
</html-lite>

Run it in your validating parser. It should validate. If not fix any typos in your files (I promise you the above is valid XML!), and run again. 

What's going on
First of all we have to add a document type declaration to our XML file, and reference our DTD.

<!DOCTYPE html-lite SYSTEM "html-lite2.dtd">

Now we declare each of the elements in turn in our DTD, 'greeting.dtd'. Here is the general syntax for declaring an element in a DTD.

General Syntax for element declarations.

<!ELEMENT [element name] ([allowed element content]) >

Note there must be white space between the keyword ELEMENT and the element name, and between the element name and the element content.

Element content

Here we declare the root element html-lite.

<!ELEMENT html-lite (head,body) >

Note the content (head, body) separated by a comma.

This means that the html-lite element can contain only these two elements. They can only occur once, and they MUSTappear in this order. 

Here is the declaration for the head element

<!ELEMENT head (title) >

Here we have a single allowed element, title. The syntax says that the head element MUST have a title, and it must occur once and only once.

Constraining element numbers.
The above construct

<!ELEMENT head (title) >

Severely constrains the content of head to one and only one element called 'title'. We can in fact allow more than one element in the content model.

We could have written this as follows

<!ELEMENT head (title)? >

<!ELEMENT head (title?) >

Both of these constructs mean the same. This would mean that a title is optional, but if we do have one we can only have one title. 

<!ELEMENT head (title)+ >

This construct means that we must have at least one title element in our head element, but we can have as many tile elements as we want.

<!ELEMENT head (title)* >

This construct means that we needn't have any title elements in our head element, but we can have as many tile elements as we want.

Obviously we want only one tile, and we want to make a title compulsory, and that is why we have chosen the form we have chosen.

Constraining element order
Similarly with the root element we have severely constrained the element content

<!ELEMENT html-lite (head,body) >

This construct means that we can only have one head element, and one body element, and they must be in that order. This is in fact what we want, but consider the body element. What would have happened if allowed content was written as follows

<!ELEMENT body (h1,p) >

This would mean that we could only have one h1 element, and one p element and they must occur in that order. Obviously we would like to have as many of these elements as we want, and they should be able to occur in any order. To do this we must make use of the 'pipe-stem ' separator (|) combined with an asterix which allows one or several of the elements.

<!ELEMENT body (h1|p)* >

The pipe stem operator tells the parser "either or", the asterix outside the parentheses says 'repeat this pattern as often as you want or not at all'.

For the record here are the constraints that other combinations would place on the parser.

<!ELEMENT body (h1|p) >

Have either a single 'p' element OR a single 'h1' element.


<!ELEMENT body (h1*|p*) >

Have as many p elements as your want OR as many h1 elements as you want

<!ELEMENT body (h1,p)* >

Have as many h1 followed by a p as you want

I.e.

<h1>firstheading</h1>
<p>first paragraph</p>
<h1>secondheading</h1>
<p>second paragraph</p>
<h1>third heading</h1>
<p>third paragraph</p>
etc.


Summary of element content constraints

* A comma separator constrains element content to the exact order that they appear. 

* A pipe stem separator means either ..or ..or

* No suffix means once and once only

* A 'hook' or query means once or not at all.

* A plus or addition sign means at least once and then as often as you want

* An asterix or star means not at all or as many as times as you want.

Parsed character data content

The way we have written our dtd, the title element, the h1 element, and the em elements can only contain what is known as parsed character data. In simple words this means plain text! In other words these elements cannot contain any mark up, just text.

<!ELEMENT title (#PCDATA) >
<!ELEMENT h1 (#PCDATA) >
<!ELEMENT em (#PCDATA) >

The following syntax is also correct

<!ELEMENT title (#PCDATA)* >
<!ELEMENT h1 (#PCDATA)* >
<!ELEMENT em (#PCDATA)* >

but the former is preferred.

Mixed content

When an element can take both parsed character data, and markup the content declaration must take a special form. This is called mixed content, and the general syntax is

(#PCDATA|[1st element type]| [2nd element type]..etc)*

We have one element that takes mixed content, the 'p' element that can take both PCDATA and the em element.

<!ELEMENT p (#PCDATA|em)* >

If we want our elements to contain mixed content this is the only permissible way to mark up the content model.
empty elements

You will have noticed that we don't have any empty elements in our html-lite document type. Let's rectify that now and add an 'img' element. We will want the img element to be able to appear any number of times in both the 'p' and the 'body' elements.

Try it out. Adding an empty element to html-lite.dtd

Make the following changes to the dtd

<!ELEMENT html-lite (head,body) >
<!ELEMENT head (title) >
<!ELEMENT body (h1|p|img)* >
<!ELEMENT title (#PCDATA) >
<!ELEMENT h1 (#PCDATA) >
<!ELEMENT p (#PCDATA|em|img)* >
<!ELEMENT em (#PCDATA) >
<!ELEMENT img EMPTY >

What's going on

We have added an element declaration for img. Notice the general syntax for an empty element declaration.

<!ELEMENT [empty element name] EMPTY >

in our case for the img element

<!ELEMENT img EMPTY >

We also added the img element to the permitted content of the body element

<!ELEMENT body (h1|p|img)* >

and to the p element

<!ELEMENT p (#PCDATA|em|img)* >

which means that body can now take any number of p, h1, or img elements, and p can take any PCDATA and any number of img, and em elements.

The ANY content

We can also declare an element to have  'ANY' content, in which case it can take PCDATA plus any of the declared elements in any number or in any order. This really puts no constraints on content and is really only of use in the developmental stage of a project. The syntax is

<!ELEMENT [element name] ANY >

Now that we have looked at how to declare elements, and how to mandate their content, let's look at how to add attribute declarations to the DTD.
Attribute declarations
We would like to add an 'align' attribute to both our 'h1' and our 'p' elements. We would also like to add an 'href' and an 'alt' attribute to our 'img' element.

We want the 'href' and the 'alt' attribute to be able to take a text string, and we would like the align attribute to be able to take the following values 'left', 'right', and 'center'.

We would also like to be able to add an id attribute of the type 'ID' to our 'h1' and to 'p' elements.

Let's see how we go about this.

General syntax for attribute declarations
Attributes for an element can be declared anywhere in the DTD after the parent element declaration. However the usual place to do it is right after the element declaration. The general syntax for an attribute declaration is.

<!ATTLIST [element name] 
[attribute name] [attribute type] [default declaration]>

There must be white space between each of the productions. 

* The 'element name' is the name of the element that is going to take these attributes. 

* The attribute name is the name of the attribute. The attribute name must be a 'name production'. The rules for naming attributes were discussed in the 'well formed ' section of this chapter.

* 'attribute type' can be one of three types, a string type, a tokenized type, or an enumerated type.

* The 'default declaration' is either default value or one of these three keywords. #REQUIRED, #IMPLIED, OR #FIXED.

* We can declare the contents of several attributes (provided they are on the same element!) using a single <!ATTLIST keyword.

Let's apply this syntax to our examples.
Try it out. Writing Attribute Declarations.

Make the following changes to html-lite2.dtd and save it as html-lite3.dtd.

<!ELEMENT html-lite (head,body) >
<!ELEMENT head (title) >
<!ELEMENT body (h1|p|img)* >
<!ELEMENT title (#PCDATA) >
<!ELEMENT h1 (#PCDATA) >
<!ATTLIST h1
	align 	(left|right|center) 	"left" 
	id 		ID				#IMPLIED
>
<!ELEMENT p (#PCDATA|em|img)* >
<!ATTLIST p
	align 	(left|right|center) 	#IMPLIED 
	id 		ID				#IMPLIED
>
<!ELEMENT em (#PCDATA) >
<!ELEMENT img EMPTY >
<!ATTLIST img
	alt 	CDATA #REQUIRED
	href	CDATA	#REQUIRED
 >

Add the following line some where in the body of to html-lite2.xml.

<body>
<h1>HTML-lite example 1</h1>
<p>This is a paragraph with some <em>emphasized</em> text.</p>
<img href="mypic.gif"/>
</body>

Save it as html-lite3.xml and run it through the parser. You will get the following error message. 

parsing:
C:\BOOK_XHT\CH8\EXAMPLES\html-lite3.xml
Parsing in the validating mode.

The above document does not parse. The following information is available about this error. Fix the error and try again.

The error is: 
Required attribute 'alt' is missing.

The error occured in the following document: 
file://C:\BOOK_XHT\CH8\EXAMPLES\html-lite3.xml
at line number: 
10
The character position is: 
25
The text of the line is<img href="mypic.gif" />
The absolute file position of the error is: 
262

When we declared our alt attribute we said that it was required, and we ommited to add it. Change line 10 to read

<img href="mypic.gif" alt="an image of me"/>

and re-parse. You should now get no errors.


What's going on.
Enumerated attribute(1)
When we declare the attribute align for the h1 element we are in fact declaring an enumerated attribute type. We give a choice of three values separated by a pipe-stem. As with element declarations this means either or.

<!ELEMENT h1 (#PCDATA) >
<!ATTLIST h1
	align (left|right|center) "left" >

In this case we have given a literal value for our default declaration, so if in fact no attribute is put on the h1 element, the parser will assume a value of "left". Note the following two points.

* The default value must be quoted.

* The default value must be one of the enumerated values!

Enumerated attribute(2)

With the p element we have used a different default declaration. We have used the XML keyword #IMPLIED.

<!ATTLIST p
	align (left|right|center) #IMPLIED >

This signals to the parser that the attribute can be put there at the discretion of the author. If the attribute is omitted then no value is assumed. 

In fact to give different defaults to the same attribute is very bad document architecture. We have done it here for illustration purposes. In the real xhtml dtd 'align' always has a default declaration of #IMPLIED. 

CDATA attribute

CDATA in this case just means a string of text. The rules for what may be in this string were explained earlier in this chapter. To sum up CDATA can consist of any character except & and < or the same kind of quotation mark that encloses the value.

<!ELEMENT img EMPTY >
<!ATTLIST img
	alt 	CDATA #REQUIRED
	href	CDATA	#REQUIRED
 >

In this case the default declaration has been given a value of #REQUIRED. If the validating parser does not see an attribute and its value (The value could just be an empty quote!) it will flag an error as we saw earlier.

Tokenized attributes.

For most practical purposes a tokenized attribute will be of the type ID. Remember that an attribute with the type ID must have a unique value through out the document, and the value must match the "name" production.

In our html-lite DTD we have given id attributes to both our h1 and our p elements.

id 		ID				#IMPLIED

Note the following points.

* It is traditional to give an element of the type ID the name 'id' but this is not compulsory.

* The value of the attribute of the type ID must be unique in the document.

* The value must match the 'name' production (i.e. start with a letter or an underscore and contain only alphanumeric content and the characters "-|_|:|." Remember that the colon is reserved for w3c usage.

In fact it can take any UNICODE extender or combining character. These are laid out in the XML spec, but is out of scope for a beginners book.

* An element can only have one attribute of the type ID. (Obvious when you think about it).

* An ID attribute can only take a default value of #IMPLIED or #REQUIRED. (Also obvious when you think about it).

There are other types of TOKENIZED attribute types, but they are really used, and a discussion of them is out of scope for this book. You are referred to the XML Spec or to a specialized XML book if you want to know more about the other tokenized attribute types.

We will also look at an example of adding attributes of a value ID when we have a look at parameter entities below. 
#FIXED default declaration

If an attributes default declaration is said to be fixed the element is always assumed to take the default declaration. For example in the XHTML DTD the pre element always takes the 'preserve' value for xml:space. 

<!ATTLIST pre
[deleted material]
  xml:space   CDATA         #FIXED    "preserve" 

Notation Attributes.
We have just put this here for the sake of completeness. 

In an XML document we may want our attribute value to have certain consequences. We may have an element called 'picture', which can take an attribute 'type' with a value of either 'vector' or 'bitmap'. 

If we give the attribute a value of 'vector' we want it opened in a draw program, if it is a bitmap we want it opened in a photo program.

We can declare a notation that allows us to give the paths of the relative programs.

<!ELEMENT picture EMPTY >
<!NOTATION vector SYSTEM " C:\Corel\Graphics8\Programs\coreldrw.exe">
<!NOTATION bitmap SYSTEM " C:\Corel\Graphics8\Programs\photopnt.exe">
<!ATTLIST picture  NOTATION (vector|bitmap)>

Now a conforming XML browser would actually open up my draw program every time it came across a vector image.

If you want to know more about notations we would refer you to a book on XML such as XML Applications.

Entities, Entity references and Entity declarations
An entity is a storage unit. A full treatment of entities is beyond the scope of this book, but we will briefly look at character entities, general entities, and parameter entities.

Let's start with a quick look at what is meant by the above terms.

Entity

The entity is the actual storage unit that contains material. In fact the complete document is an entity called a 'document entity'. Entities have names, and the name given to the entity must match the 'name production'.

Entity reference

An entity is referred to by an 'entity reference'. This may be a character entity reference, a general entity reference, or in the DTD a parameter entity reference. When a parser comes across an entity reference, it will expand it so that the reference is replaced by the content as set forth in the entity declaration. 

Entity declaration

Entities other than character entities have to be declared, and they are declared in the DTD. They can be declared anywhere in the DTD, but it is usual to put general declarations at the end of the DTD, and parameter entities at top of the DTD. As we will see parameter entities have to be declared before they are referenced.

Let's have a look at the different kind of entities
Character Entities
A character entity references a single Unicode character by using its Unicode number. This can be either a decimal number or a hexadecimal number.

The general syntax for this is:

&#[Decimal Unicode number];

or

&#x[Hexadecimal Unicode number];

This can be very useful for certain symbols. For example accented characters, the copyright symbol (Unicode decimal number 169, hexadecimal number a9), or the registered trademark symbol (Unicode number 174, hexadecimal number ae)
UNICODE
The latin character set can be represented by the ASCII numbers from 0 to 255. Each number represents one bit. However if we want to represent the character sets of other languages then we need far more than the 255 characters represented by ASCII. XML uses UNICODE characters. Each character is represented by 2 bits and is known as a 'wide character'. Because of this UNICODE can represent 256 x 256 or 65536 characters. Until we start trading with the Klingons (their written language is notoriously complex. That's why they are always in such an ugly mood and fighting.) this should be sufficient to represent the character sets of this world!

A good introduction to Unicode is given at:

http://www.unicode.org

Try it out. Using Character entities in an XHTML document.

Fire up your editor and type the following.

<html>
<head>
<title>Examples of character entities.</title>
</head>
<body>
<h1>Examples of character entities.</h1>
<p>This is the registered trademark symbol, unicode decimal number '174'.  &#174;</p>

<p>This is the copyright symbol written using a hexadecimal number, unicode hexadecimal number 'a9' &#xa9;</p>

</body>
</html>

Here is what you will see in IE5.



What's going on

A 'knowledge' of unicode is built into XML parsers, so when the parser comes across this line

<p>This is the registered trademark symbol, unicode decimal number '174'.  &#174;</p>

It knows that it is to display the entity reference &#174; as a registered trade mark symbol. 

It also recognizes this line

<p>This is the copyright symbol written using a hexadecimal number, unicode hexadecimal number 'a9' &#xa9;</p>

as containing a hexadecimal reference, and displays it accordingly.




CAUTION.
Older HTML browsers may not recognize hexadecimal entity references, nor may they recognize decimal numbers greater than 255. Therefore use these with caution in your XHTML pages.


General Entities
A general entity allows an entity reference in our document to refer to some text in our dtd. The entity is declared in the DTD using an entity declaration.

The entity declaration

The entity declaration must be declared in the DTD. It takes the following syntax

<!ENTITY [entity name] "[entity declaration]">

Now when ever the entity name  is referenced in the body of the document the parse will substitute the text in the entity declaration for the reference.

The entity name must be a 'name production'
The entity reference

An entity is referenced with the following syntax.

&[entity name];

Note there are no spaces between the ampersand, the entity name, and the colon. Lets try this out.

Try it out. Using an entity reference

Make the following changes to you basic html-lite document and save it as entity2.xml

<?xml version="1.0" ?>

<!DOCTYPE html-lite[
<!ENTITY warning "Learning XML can be an addictive process"> 
]>
<html-lite>
  <head>
    <title>HTML-lite example 1</title>
  </head>


<body>
  <h1>HTML-lite example 1</h1>
  <p>This is a paragraph with some <em>emphasized</em> text.</p>
<p>&warning;</p>

</body>
</html-lite>

This is what you will see when you run it.



What's going on

When the parser comes across the entity reference &warning; , it goes to the DTD to look for an entity declaration and substitutes the appropriate text, in this case "Learning XML can be an addictive process"

General entities in XHTML
XHTML contains numerous pre-defined entities, and these can be found in appendix?

All of these entities are characters that in fact could be handled just as well by character entities. Thegeneral entities  are however easier to remember. For example here are the general entities for the two examples we looked at under "character entities. The copyright symbol is &copy;, and for the registered trade mark symbol the entity reference is &reg;

Pre-defined entities

All XML parsers are required to recognize certain so called predefined entities. These are the entities for the opening an closing angle brackets, for the single and double quote, and for the ampersand.

These should be expanded even in the absence of a DTD, although if a DTD is present they should be declared in the normal way.

* &lt;		expands to	<

* &gt;		expands to	>


* &amp;		expands to	&


* &apos;		expands to	'


* &quot;		expands to	"


Parameter Entities

Parameter entities are used in external DTD's (They are illegal in internal DTD's). When a DTD becomes large there are often large quantities of repeated code. A parameter entity allows us to place all the code in a single place.

Parameter entity declarations.

The syntax for declaring a parameter entity is

<!ENTITY % [entity name] [entity declaration]>

Parameter entity references

A parameter entity reference takes the form

%[entity name];

Note there are no spaces between the '%' and the entity name, and the entity name and ';'.


For example at the top of the DTD we may have

<!ENTITY % inline-style "i|b|u">


Now when ever the parser sees %inline-style; (Note NO space between pct sign and entity name) it will expand it to "i|b|u".
Thus 

<!ELEMENT p (img | %inline-style;)*

is expanded by the parser to

<!ELEMENT p (img | i|b|u)*

One 'quirk' of entities is that the first entity takes precedence. Thus if we have two or more entity declarations of the same name, the first will be the entity declaration that is expanded. This actually allows us to over ride an entity in a document.

Lets use a parameter entity in html-lite.

Try it out. Adding a parameter entity to html-lite

We would like to add some core attributes to all our html-lite presentational elements, in other words img, p, h1, and em. The attributes that we would like to add are:


  id          	ID             	#IMPLIED
  class       	CDATA        #IMPLIED 
  title 		CDATA	#IMPLIED


Open html-lite3.dtd and make the following changes to it


<!ENTITY % coreattrs
 "id          ID             #IMPLIED
  class       CDATA          #IMPLIED
  title      CDATA           #IMPLIED"
  >

<!ELEMENT html-lite (head,body) >
<!ELEMENT head (title) >
<!ELEMENT body (h1|p|img)* >
<!ELEMENT title (#PCDATA) >

<!ELEMENT h1 (#PCDATA) >
<!ATTLIST h1
	%coreattrs;
	align (left|right|center) "left" >

<!ELEMENT p (#PCDATA|em|img)* >
<!ATTLIST p
	%coreattrs;
	align (left|right|center) #IMPLIED 
>
<!ELEMENT em (#PCDATA) >
<!ATTLIST em
	%coreattrs;
>
<!ELEMENT img EMPTY >
<!ATTLIST img
	%coreattrs;
	alt 	CDATA #REQUIRED
	href	CDATA	#REQUIRED
 >

Save it as html-lite4.dtd

Now open html-lite3.xml and alter/ add the following

<!DOCTYPE html-lite SYSTEM "html-lite4.dtd">
........
<p id="1">This is a paragraph with some <em>emphasized</em> text.</p>
<p id="1">A second paragraph.</p>

Note that we have deliberately given the id a bad name and duplicated it!

Run it through the parser. Here is the error message we will recieve.

The error is: 
A name was started with an invalid character.

The error occured in the following document: 
file://C:\BOOK_XHT\CH8\EXAMPLES\html-lite4.xml
at line number: 
9
The character position is: 
11
The text of the line is<p id="1">This is a paragraph with some <em>emphasized</em> text.</p>
The absolute file position of the error is: 
184


Fix that error by adding an underscore in front of the number and re run. Now we get this error message.

The error is: 
The ID '_1' is duplicated.

 Now give both of them a unique name and they will validate.

What's going on
Declaring the entity

Parameter entities, like general entities, have to be declared before they are referenced.

<!ENTITY % coreattrs
 "id          ID             #IMPLIED
  class       CDATA          #IMPLIED
  title      CDATA           #IMPLIED"
  >

note the following.

* The beginning of a parameter entitity declaration is announced in just the same way as the beginning of the general entity reference by the keyword '<!ENTITY' .

* The percentage sign '%' tells the parser that this is a parameter entity. Notice that there is white space between '<!ENTITY' and '%' and between '%' and the entity name.

* The entity name must be a name production. I.e. it must start with either an underscore or a letter and just contain alpha-numeric content or the characters     (-|_|.|:)

* The actual content of the entity declaration is quoted.

* The whole is closed with a closing angle bracket.

Parameter entity references
Every time the entity is referenced

	%coreattrs;

The parser will expand the entity to-

  id          ID             #IMPLIED
  class       CDATA          #IMPLIED
  title       CDATA          #IMPLIED

Note the following.

* The entity is referenced using the percentage sign, the entity name 'coreattrs', followed by a semi-colon. Note that there is NO white space between these two characters and the entity name.

* This whole construct is known as a 'parameter entity reference'.


Modules

Parameter entities allow us to break up our DTD into modules. A full treatment of this is beyond the scope of this book, but note that the ability to create modules is what makes it possible for us to add our own element sets to the XHTML document.

XHTML 1.1 is in fact a modularized DTD. These modules can be mixed and matched allowing us to create the different profiles used by different browsing devices.

We will look at this a little in the next chapter.
Summary
In this chapter we took an introductory course in XML. 

* We looked at Well-formed documents

* We looked at Valid documents

* We learnt how to write a basic XML DTD

We should be able to now understand the syntax of both well-formed and valid XML documents. We should now have an understanding of basic XML structure and we should be able to glean useful information from an XML DTD. For more on this subject look at either the XML specs, or consult a specialized text on XML.
Appendix

Source code listing for parser.htm

<html>

<!--
	Author: 	Frank Boumphrey
	Last Revised:	7:44 AM 7/12/99
	Version:	1.4
	Notes(1):	This parser uses the Microsoft parser contained 
			in the MSXML.DLL. This .dll comes with IE5.
	Notes(2):	This was originally written for the HTML Writers guild
			course on XML. This version was revised for "Beginning XHTML"
			from Wrox press. 
	Notes(3):	The code may be freely copied and distributed provided 
			this versioning information is distributed with it in 
			the head of the document.
-->

<head>
<title>Validating XML Parser</title>
</head>
<body bgcolor="white">
<h1>XML parser</h1>

<p>This parser uses the microsoft XML validating parser built into IE5. 
<br>You must be running IE5 or better to use this parser.</p>
<form name="parseselect">
<div><b>Select the type of parsing operation you wish to perform on the XML document.</b></div>
<table>

  <tr><td>Validate</td><td><input type="radio" name="parsechoice" value="valid"  checked="true"></td></tr>
  <tr><td>Well Formed</td><td><input type="radio"  name="parsechoice"  value="wellformed"></td></tr>
  <tr><td>Expand entities only</td><td><input type="radio" name="parsechoice" value="getentity"></td></tr><br>

</table>
</form>

<h4>Type in the path name or browse for the file you wish to parse.</h4>

<form name="parser">
	<input type="file" id="xmlpath" name="xmlpath" value="greeting2.xml" size="40">
	<input type="button" onclick="parsexml(parser.xmlpath.value)" value="Parse">
    <h4>The results will be given in the box below.</h4>
	<textarea name="ta" cols="50" rows="10"></textarea>
</form>

<script>

function parsexml(xpath)

  {
  //This function creates an instance of the XML dom from the file
  //and either loads it or gives information about the errors encountered
  //when it tries to load it.

	//=======================================================
	//This function may be freely copied and distributed 
	//provided this notice is retained.
	//Copyrights
	// Frank Boumphrey, Wrox press and the HTML Writers Guild
	//========================================================

  var oXDOM, mydoc,errstr
	errstr="parsing:\n" + xpath +"\n"

	 oXDOM=new ActiveXObject("Microsoft.XMLDOM")
	

if(parseselect.parsechoice[0].checked==true)
	{
	errstr=errstr +"Parsing in the validating mode.\n\n" 
	oXDOM.validateOnParse = true
 	oXDOM.resolveExternals=true
	}
else if(parseselect.parsechoice[1].checked==true)
	{
	errstr=errstr +"Parsing in the well-formed mode only.\n\n" 
	oXDOM.validateOnParse = false
 	oXDOM.resolveExternals=false
	}
else if(parseselect.parsechoice[2].checked==true)
	{
	errstr=errstr +"Parsing in the well-formed mode only and expanding entity references.\n\n" 
	oXDOM.validateOnParse = false
 	oXDOM.resolveExternals=true
	}

	oXDOM.load(xpath)

       if (oXDOM.parseError==0)
	{
		errstr=errstr +"The above document parses\n\n" 
	
	 	errstr=errstr +"The root node of this document is:\n " + oXDOM.documentElement.nodeName
	}
	else
	{
		errstr=errstr +"The above document does not parse. The following information is available about this error. Fix the error and try again.\n\n" 
		errstr=errstr + "The error is: \n"	
		errstr=errstr + oXDOM.parseError.reason +"\n"	
		errstr=errstr + "The error occured in the following document: \n"	
		errstr=errstr + oXDOM.parseError.url +"\n"
		errstr=errstr + "at line number: \n"	
		errstr=errstr + oXDOM.parseError.line +"\n"
		errstr=errstr + "The character position is: \n"	
		errstr=errstr + oXDOM.parseError.linepos +"\n"
		errstr=errstr + "The text of the line is"	
		errstr=errstr + oXDOM.parseError.srcText +"\n"
		errstr=errstr + "The absolute file position of the error is: \n"	
		errstr=errstr + oXDOM.parseError.filepos +"\n"
		
	}

	document.parser.ta.value=errstr
}
function getxmlfile()
  {
	//alert(parser.xmlpath.value)
	window.location.href=parser.xmlpath.value
  }
</script>
<form>
<h4>Click this button to view the XML file</h4>
<input type="button" value="View XML File" onclick="getxmlfile()">
</form>

</body>
</html>