Platinum Edition Using HTML 4, XML, and Java 1.2:Creating XML Documents

To access the contents, click the chapter and section titles.

Platinum Edition Using HTML 4, XML, and Java 1.2
(Publisher: Macmillan Computer Publishing)
Author(s): Eric Ladd
ISBN: 078971759x
Publication Date: 11/01/98

Table of Contents

CHAPTER 13
Creating XML Documents

by Simon North and Jim O'Donnell

In this chapter

Entity References 342

CDATA Sections 346

Processing Instructions 347

Markup Declarations 348

Element Declarations 348

Element Content Models 349

Attribute Declarations 353

Well-Formed XML Documents 356

Sample XML Applications 357

Entity References

As you learned in Chapter 12, “Anatomy of an XML Document,” entities are normally external objects, such as graphics files that are meant to be included in the document. To be able to reference these external entities, you must have a DTD for your XML document. You will learn about these entities when you learn about DTDs, but one other type of entity, called an internal entity, you can use already, and it can save you a lot of unnecessary typing.

Internal entities look very much like character references but have one important difference—you must declare an internal entity before you can use it.

Entity Declarations

The declaration of an internal entity has the following form:

<!ENTITY name “replacement text”>

Having declared this entity, every time that the string &name; now appears in your XML code, it will be automatically replaced with the replacement text (which can be as long as you like) by the XML processor. Judiciously used, entity references can save you a lot of typing.

Predefined Entities

Character references enable you to enter characters that you might not be able to enter normally from your keyboard. A variation on this theme is the set of so-called predefined entities. These are characters that you can enter quite normally, but you shouldn’t because they can all too easily be mistaken for markup characters. To refresh your memory, the set of predefined entities is shown in Table 13.1.

Table 13.1 The Predefined Entities

Character	Replacement

&	& or &#38;
‘	' or '
>	> or >
<	< or &#60;
“	" or "

You will see that the table now gives you two options: You can enter a named entity, for example ', or you can enter character reference ' to represent the character. The character references for the ampersand (&) and the less than (<) character are, however, special cases, and so the character references are “double escaped”; the reasons for this will be explained next when you learn about entity references.

The Benefits of Entities

You can think of entity references as being almost a kind of macro. They can be real time savers when you want to use sections of text several times. Consider the example shown below, where the person’s name is an entity reference:

<?xml version=”1.0"?>
<!DOCTYPE home.page [
   <!ENTITY club “Antidisestablishmentarianism Club of America”>
]>
<home.page>
   <head>
      <title>The &club; Home Page</title>
   </head>
   <body>
      <h1>Welcome to the &club; Home Page!</h1>
      <para>Hello, I am the chairman of the &club; and this is our
            club’s Home Page...</para>
   </body>
</home.page>

By using an entity reference in this way, you would only have to enter the name once, in the entity declaration, instead of having to search for and change every occurrence of the string in the text. Used in this way, entity references can make the task of creating and maintaining XML documents quite a bit easier.

Some of the Dangers of Using Entities

You’ve seen how handy internal entity references can be as a kind of shorthand for entering pieces of text and as a means of dealing with variable content. Obviously, with a little thought and advance preparation, entity references can save you a lot of time and effort later on.

A feature this handy naturally raises a simple question: Could this be used to insert markup, too? It’s an attractive idea and a natural thing to want to do. You can put markup into replacement text, subject to a few restrictions. You need to think it out quite carefully beforehand to avoid some unpleasant surprises.

The first thing you must remember is that the XML will process the contents of the entity replacement text when it expands the entity reference. Therefore, you must not escape any markup characters in the replacement text, you must double escape the characters. Consider this simple example:

<!ENTITY dangerous “Black &#38; White”>

When the XML processor sees the entity reference &dangerous; in the XML document, it will immediately expand (de-reference) the predefined entity before it inserts the replacement text. The following XML code seems harmless enough, but we’ll look at what happens, step by step:

<text>This is not a &dangerous; choice.</text>

1. The XML processor sees the entity reference &dangerous; and looks for the replacement text.

2. Finding Black & White, the XML processor de-references this to Black & White.

3. The XML processor inserts the replacement text and the resulting XML code is

<text>This is not a Black & White choice.</text>

4. The XML processor then tries to parse the ampersand and will report an error because & has not been declared as an entity.