• Elements and their allowed content
• Attribute lists for elements
• Entities that make DTDs more modular
• Comments that make DTDs more understandable

You can view the domino DTD file in any text editor. If you accepted the defaults when installing Notes, the path of the file is Lotus/Notes/domino_6_0.dtd.

Elements

An element is a tag, defined as follows:

<!ELEMENT tagname ( content-model ) >

where tagname is the name of the tag. Tag names are case-sensitive. The content-model is an expression stating what content can appear inside the element. It can also contain nested tags. An element is used within start and end tags. For example, the viewentry element in the Domino DTD is defined thus:

<!ELEMENT viewentry ( entrydata* ) >

This element is used in an XML output as follows:

<viewentry children="3">

<entrydata columnnumber="1">

<text> Joe Smith </text>

</entrydata>

</viewentry>

The operators you can use to structure the content model are:

• OR ( | ) means you can choose one of the elements
• comma ( , ) means the elements must be in the specified sequence
• asterisk ( * ) means 0 or more of the elements are required
• plus ( + ) means 1 or more of the elements are required
• question mark ( ? ) means 0 or 1 element; the element is optional.
• parentheses ( () ) are for grouping elements

The following example shows the use of operators in structuring the content model:

<!ELEMENT acl ( role*, aclentry+, logentry* )>

In this case, an <acl> element can contain any number of <role> elements, followed by one or more <aclentry> elements, followed by any number of <logentry> elements.

Another example of operators is:

<!ELEMENT text ( #PCDATA | break )* >

Here a <text> element can contain any quantity of either plain text, or <break> elements, in any order. #PCDATA is parsed character data, which means it is plain text that does not recognize extra spacing and requires that characters, like an ampersand (&), for example, be represented by a character entity, such as &amp;. The table below displays the characters that are internal entities which are predefined in XML and cannot be included in parsed character data unless they are represented in the specified XML format:

Character	XML represention
< (less than)	&lt;
> (greater than)	&gt;
' (apostrophe)	&apos;
" (quotation marks)	&quot;
& (ampersand)	&amp;

#PCDATA has to be the first of the series of choices, where the whole choice group is marked with an asterisk. See Entities for more details.
Attributes

The attributes for any element are declared in the following manner:

<!ATTLIST tagname

attr1	type1	default_value1
attr2	type2	default_value2
	...

>
The attributes, along with their types and default values, are defined for the tagname element.

Consider this example for the element with the tagname book:

<!ATTLIST book

title	CDATA	#REQUIRED
isbn	CDATA	#IMPLIED
cover	(hard|paper)	#IMPLIED
format	( bound|looseleaf|scroll|parchment )	"bound"

>
This example defines four allowed attributes for the <book> element: title, isbn, cover, and format. If there is no other ATTLIST declaration for <book>, then these are the only attributes allowed. Any others are illegal. The title attribute can have any value, but it must appear because its default_value equals #REQUIRED. A <book> element without a title attribute is not valid according to this DTD. The isbn attribute can have any value, or can be omitted entirely. The cover attribute can have one of two values: "hard" or "paper." Any other value is illegal, but the attribute can also be omitted. The format attribute can have one of four possible values, and if it is omitted, a validating parser will provide "bound" as its value just as if format="bound" had appeared in the XML content.

All attributes are fundamentally strings, as shown in this table:

Attribute value	Means
CDATA	Unparsed character data, which means any text string.
NMTOKEN	A single name token composed of letters, numbers, hyphens, underscores, or colons.
NMTOKENS	A list of name tokens separated by spaces.
ID	Name that identifies an instance of an element in a document. No two ID attributes can share the same name.
( a | b | c )	"a" or "b" or "c". You can specify any of the following as the default value: one of the choices from the enumerated list, "a," for example #REQUIRED, indicating that one of the enumerated choices must be supplied in the document #IMPLIED, indicating that no value is required
#IMPLIED	Optional. A value is not required. The application will supply a default value.
#REQUIRED	The value must be supplied in the document. There is no default value.
'literal'	The default value to use if a value is not specified in the document.
#FIXED 'literal'	The default value to use. If the document specifies a value, it must be equal to this fixed value.

Since attribute values are strings, they are always enclosed by quotation marks in XML. The order of attributes in the ATTLIST declaration is irrelevant (just as it is in XML data), and white space can be used to make the DTD more legible.

Entities

There are three types of XML entities:

• Internal: Defined in the DTD as replacement values.
• External: Defined in an external DTD or DTD fragment.
• Parameter: Expansion macros for simplifying DTDs.

<!ENTITY productName "2000 Calendar">

Then you could reference it in your .xml file as follows:

<response>Thank you for purchasing the &productName; from us.</response>

This means that in January of 2001, you could update the DTD to change the value of the &productName; entity to "2001 Calendar" and the change would be reflected in all XML documents that reference that entity.

The entities defined in the Domino DTD are parameter entities. Parameter entities are entities created to be referenced exclusively within the DTD itself. They facilitate code reusability and decrease the size of the DTD. You cannot reference parameter entities in an .xml file.

The Domino DTD entities serve as macros that are declared as shown below:

<!ENTITY macroname "macrocontent" >

For example:

<!ENTITY	% string	"CDATA" >
<!ENTITY	% book.formats	"bound|looseleaf|scroll|parchment" >
<!ENTITY	% book.covers	"hard|paper" >

The above entities are used as follows:

<!ATTLIST book

title	%string;	#REQUIRED
isbn	%string;	#IMPLIED
cover	( %book.covers; )	#IMPLIED
format	( %book.formats; )	"bound"

>
The %book.formats; entity, which has been defined as a list of formatting options, replaces the list in the attribute list definition for the book element. The name of the entity is encased in percent and semicolon, and the contents are interpolated like a C macro. Using the entity to represent the formatting options list increases the efficiency of the DTD because the entity can be used more than once. For instance, if a manual element existed in this DTD, in addition to the book element, which only differed from the book element in that it was only available in soft cover, but was available in the same formatting options, the %book.formats; entity could be used again in defining the attribute list for the manual.

Comments

Comments within a DTD are enclosed as shown below:

<!-- comment text, anything except two dashes. -->

See Also

The Domino DTD
Using XML in Lotus Domino Designer
XML for Domino

Glossary