Copyright © TIBCO Software Inc. All Rights Reserved

DTD

Resource

The DTD resource of the XML Tools palette enables the creation of a DTD (Document Type Definition), as defined by the W3C’s XML 1.0 Recommendation.

A DTD shares the same role as an XML Schema, describing the vocabulary and structures that may appear within an XML instance document. While DTDs are supported in XML 1.0-compliant parsers and applications, they offer very limited data typing and are considered the 'first generation' of XML schemas.

When a DTD resource is selected in your project, a set of new panels, menu options, and toolbar buttons are provided, helping you build and edit your DTD from a variety of different perspectives. Each panel provides access to a different set of tools. The multiple panels may show information simultaneously, but all of them combine to present a consistent view of your schema. This chapter describes each of the panels in detail.

For a hands-on demonstration of the editing environment, see DTD Exercise.

Configuration Panel

When editing a DTD resource, the configuration panel provides two tabs for setting or viewing high-level properties.

Configuration

The Configuration tab has the following fields.

Table 23 Configuration tab Field

Field	Description
Name	This is the name of the file when persisted. The *.dtd suffix will be automatically added.

Statistics

The Statistics tab is not editable. The tab displays the number of times a schema component type is used. The Statistics tab has the following fields.

 

Table 24 Statistics Tab Fields

Field	Description
Elements	The number of element declarations is displayed.
Complex Types	The number of complex type definitions is displayed. (This is an XML Schema metric only.)
Attributes	The number of attribute declarations is displayed.
Attribute Groups	The number of attribute group definitions is displayed.
Model Groups	The number of model group definitions is displayed.
Data Types	The number of user-derived datatype definitions is displayed. (This is an XML Schema metric only).
Namespaces	The number of namespace declarations is displayed. (This is an XML Schema metric only.)
Included Modules	The number of included modules is displayed.
Notations	The number of notation declarations is displayed.
Processing Instructions	The number of processing instructions is displayed.

Toolbar

For a description of the buttons that appear on the toolbar when editing DTD resources, see Toolbar Buttons.

Schema Menu

A Schema menu becomes available when editing a DTD resource. The Schema menu contains two submenus, View and Tools.

The View menu provides options to control the panels used for editing, organizing, and viewing your schemas. The Tools menu includes options for searching or editing your schema, checking your schema for errors, and defining reusable schema components.

The Schema menu options are described in Table 7.

Elements Panel

The elements panel enables you to view, create, and edit element and attribute declarations. The elements panel is typically the place you'll start defining your schemas.

The panel is divided into two parts: a graphical view of the content model (the content model diagram) and an editable list of element declarations and their content models (the element list).

The Element List

The element list, located at the bottom of the elements panel, is where much of the creation and editing of element declarations takes place. Each element is listed in a row of the table. Information that defines each item appears in columns across the table and includes the following (from left to right):

Table 25 Element List

Column	Description
Row Selector/Error Indicator	This column allows you to modify the row and detect errors in the declaration. See Common Columns In Tables for more information about this column.
Included Document Indicator	This column indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables for more information about this column. Warning: Any changes made to unlocked declarations of an external parameter entity will be reflected in the external schema as well.
Element Name	A new element can be created by clicking on a blank row under the Element column, and then entering a name. To edit an element name, click on an existing name in the Element column Note: Element names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.
Content	The content column is used to specify the type of content model to be created. When the user tabs to this column, a Content Type button appears, providing a menu of the following choices. • ANY — The content model contains any combination of elements and/or character data (text). • EMPTY — When an element has no content at all, its content model is empty. Essentially, a model is defined that allows only elements in its content but does not actually declare any elements, so the type's content model is empty. • Mixed — In a mixed content model, an element contains other elements interleaved with character content. Character data can appear alongside child elements and is not confined to the deepest child elements. • Elements — The content model contains elements only. • Text — The content model contains only character data (text). A character-only element can represent an atomic data type whose value is encoded as character data. • Type — Data types that constrain text -- like integer or date -- are not afforded by DTDs. Accordingly, selecting the Type option is equivalent to selecting the Text option.
Content Model	The Content Model column displays the content model of the elements and provides a set of tools for creating and editing content models. Note: If text is selected as content, the name of this column switches to Data Type, to indicate that the element content is text. The Data Type column should remain empty when text is the specified content. Users who are comfortable with occurrence and sequence indicator syntax can enter element content models directly by typing them in the Content Model column. For users not yet comfortable with occurrence and sequence indicators, a series of buttons are provided to help the user create and edit content models. (See Building Content Models: Occurrence and Sequence Indicators for more information.) The Insert menu provides a quick way to add elements (or internal parameter entities representing element content) that have been previously defined. The selected item is inserted at the current location of the cursor. (See Example: Building a Content Model and Building Content Models with Reusables (Internal Parameter Entities) for more information.) Note: To create a reusable model group (internal parameter entity representing element content), choose Create Model Group... from the Insert drop-down menu. Alternatively, parameter entities can be defined and edited by way of the Schema>Tools menu.
Attributes	The Attributes column allows the user to specify which attributes may be used for a particular element. If an attribute name is entered which does not yet exist, it is automatically created with a default data type of string and with no constraints. (The declaration can be edited in the attributes panel at any time.) When the user tabs to an Attributes column, an Insert Attribute button appears. Click the button to access a menu listing previously defined attributes and reusable attribute groups. Selecting an attribute name or a reusable adds it to the element or complex type being defined.

The element list can be sorted at any time by clicking on one of the column headers. For example, to sort the list by the name of the element, click on the Element column header. Or, to sort the list by content model, click on the Content Model column header, and so forth. Shift-clicking on a column header sorts the column in descending order.

Building Content Models: Occurrence and Sequence Indicators

For element content models, buttons are provided for applying sequence and occurrence indicators. Table 26 describes the Occurrence indicators. Table 27 describes the Sequence indicators.

Table 26 Occurrence Indicators

Occurrence Indicator	Meaning	In Content Model column, click...
None	The element must appear once and only once.	(This is the default occurrence).
?	The element (or group of elements) may appear zero or one times. The element is optional, but is only allowed to appear once if used.	Optional but not Repeatable
+	The element (or group of elements) must appear one or more times. The element is required to appear at least once, but multiple consecutive occurrences may be present.	Repeatable but not Optional.
*	The element (or group of elements) may appear zero or more times. The element can appear as many times consecutively as needed, or even zero times.	Repeatable and Optional.

 

Table 27 Sequence Indicators

Occurrence Indicator	Meaning	In Content Model column, click...
|	Can be read as 'or'. Creates content model with particles enumerated (only one may be chosen).	Choices
,	Can be read as 'followed by,' requiring that the elements or groups of elements appear in the precise sequence indicated	Sequence
()	Groups elements, allowing a set of choices or a sequence to be used anywhere that a single element can appear.	()

Occurrence and Sequence indicators combine to make it possible to describe complex structures. For example, a memo might allow multiple entries in its To: and From: fields, multiple (or zero) entries in its Cc: field, a single entry for the subject, required content for the body, and an optional set of initials at the bottom for the typist. A MEMO element might therefore have the following content model:

 

(To+, From+, Cc*, Subject, Body, Typist?)

This declaration requires the MEMO element to contain, in sequence, one or more To elements, one or more From elements, zero or more Cc elements, a single Subject element, a single Body element, and zero or one Typist elements.

In other cases, a document needs to provide choices. A chapter might require an introduction, but then permit any combination of sections or sidebars. Sequence indicators, in combination with occurrence indicators, can make this possible. The content model for a chapter element might therefore look like this:

 

(Intro, (Section | Sidebar)*)

The Intro element could appear once (and only once) at the start of the chapter, and then Section or Sidebar elements could follow in any order. (This model is read as “an Intro element followed by zero or more Section or Sidebar elements”.)

Example: Building a Content Model

This section steps you through building a content model using the buttons provided in the Content Model column. Figure 49 shows a completed content model.

Figure 49 A Completed Content Model for a Book Element

You will build the content model for an element based on the structure of a book. The content model would likely include several elements, including a Title, an Author, multiple Chapters, maybe an Appendix (or several), perhaps a Glossary, and possibly an Index. Assuming these elements are already declared, the steps to build the content model for Book appear below:

1.	In the row for Book, click in the blank cell under the Content Model column. This is where the entry for the content model will be created. A series of buttons will appear. You should see the text cursor blinking inside the parentheses.

Figure 50 Content Model Column

2.	Click the Insert button. A pull-down menu of all the element declarations within the file appears.

Figure 51 Element Declarations

3.

Select the first element to be part of the content model (in this case, we'll start with Title). Repeat this step, selecting each element that is part of the content model. It's best to select the sub-elements in sequence if possible, because as each sub-element is selected, a comma is inserted between items by default to indicate that they are in sequence. The sub-element will always be inserted where the cursor is placed in the content model.

Figure 52 Content Model

If the elements for the content model have not been previously declared, type them in within the parentheses. When the content model is completed, you will be prompted to auto-create (declare) the new elements.

4.

Which items may be repeatable? Within a book, the chapters usually occur more than once, so this sub-element needs to be indicated as a repeatable item. Highlight Chapter in the Content Model, and click on the Repeatable button. This adds a '+' indicator after Chapter, to indicate it is repeatable. Likewise, there may be more than one appendix, so highlight Appendix and click Repeatable to add a '+' indicator after Appendix.

Figure 53 Repeatable Button

5.

Which items are optional? Within a book, a glossary or index may not always occur, so these sub-elements need to be made optional. Highlight Glossary, and click the Optional button. Likewise, highlight Index, and click the Optional button. This will place a '?' after each of these sub-elements, to indicate they are optional.

Figure 54 Optional Button

6.

Appendix is also an optional item (not all books have appendices). Highlight Appendix and click the Optional button. Because Appendix is now both optional and repeatable, it is indicated with an '*' after it. Press the <Enter> key or click anywhere else in the element list panel to complete the content model.

Figure 55 Adding Appendix

This example did not require the use of the Choices button, which indicates choices between several sub-elements (sub-elements are separated by an '|' indicator).

Building Content Models: Content Model Editor

If the space provided by the Content Model column is too small to see all of an element content model, select Expand from the Schema > View menu or press the Ctrl-E keys to bring up the Content Model Editor dialog box. The Content Model Editor provides more room for editing, making it easier to work with larger content models, and gives easy access to the elements and reusables (internal parameter entities). To add an element or reusable to a content model, click on its name. Occurrence and Sequence indicator buttons are also available in the editor. The Apply button adds the edited content model to the list, but leaves the editor open. The Cancel button closes the editor without making any changes to the content model in the list, while the Save button closes the editor and makes the changes. The Content Model Editor is shown in Figure 56.

Figure 56 Content Model Editor

Building Content Models with Reusables (Internal Parameter Entities)

While breaking schemas into modules is helpful in large-scale situations where entire sets of declarations are shared within schemas, there are many cases where smaller chunks of declarations can be usefully shared and centrally managed. The reusables (internal parameter entities) editors allow you to define pieces of declarations, which you can then reuse as appropriate. If you later need to make changes to that content, you just change the reusable, and all of the declarations using that reusable will be updated automatically.

When defining new reusables, four editors, described in the table below, are accessible by way of the Schema menu (Schema > Tools > Define Reusables). For each editor, you enter the name of the reusable in the text box at the top of the window, and its content in the large text area.

Table 28 Reusable Editor

Resuable Editor	Description
Model Group	Use this editor to create model group reusables (parameter entities), which store content models that can be included in element content models. These reusables can provide the entire content model or be included as part of a larger content model. Model Group reusables must contain acceptable element content models.
Attribute Group	Use this editor to create a group of attribute declarations (as a parameter entity), allowing the same group of attributes to be applied to multiple elements. Attribute Group reusables must contain sets of attribute names, separated by commas.
Constraints	Use this editor used to express the limitations placed on attributes with enumerated values. Constraints reusables (parameter entities) must list acceptable values separated by vertical bars.
Text	Use this editor to create reusable text (parameter entity).

While you can edit reusables directly in the Parameter Entities Tab of the advanced panel, it is generally safer to use the reusable editors, especially for attribute sets. Direct editing is acceptable, but you'll need a firm understanding of XML 1.0 DTD syntax.

Once your reusables are created, they become available as choices by way of the Insert button within the Content Model and Attributes column of the element list. Notice that parameter entities, when referenced, are prepended with a ’%’. Figure 57 illustrates the use of a reusable within a content model.

Figure 57 Referencing a Reusable Parameter Entity (Internal)

To edit or delete an existing group definition, select the Edit Reusables option of the Schema menu (Schema > Tools > Edit Reusable).

The Content Model Diagram

The content model diagram of the types panel graphically displays the content models in a DTD resource. It presents the relationships between elements (that is, parent elements, child elements, and so on) with diagrams and provides additional information about elements, such as their attributes and occurrence and sequence within a content model. You can use the content model diagram to read, explore, or edit your schemas.

See Content Model Diagram for more information about the content model diagram.

Attributes Panel

When selected from the Schema > View menu or upon clicking the Attributes button on the toolbar, the attributes panel becomes the primary panel for editing. The attributes panel is used to view, create, and edit attribute type declarations. While you can also create an element’s attribute in the element list, the attributes panel is required to specify an attribute’s data type, edit its constraints, indicate its use, and set a default value. The attributes panel is shown in Figure 58.

Figure 58 Attributes Panel

Each attribute is listed in a row of the panel. Information associated with each attribute appears in columns across the panel and includes the following (from left to right).

Table 29 Attributes in the Panel

Column	Description
Row Selector/Error Indicator	This column allows you to modify the row and detect errors in the declaration. See Common Columns In Tables for more information about this column.
Included Document Indicator	This column indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables for more information about this column.
Attribute Name	A new attribute can be created by clicking on a blank row under the attribute name column, and then entering a name. To edit an attribute type name, click on an existing name in the attribute type name column. Note: Attribute names must begin with a letter and may contain other letters, numbers, underscores, dashes, and periods.
Element	The Element column references the element to which an attribute belongs. You can enter the element to which an attribute belongs by typing its name in the element column. If the same attribute needs to be assigned to multiple elements, those assignments should be made in the Attributes column of the Element List area of the elements panel. If an attribute is used by multiple elements, it will be listed in the attributes panel as shared. To bring up a list of the multiple elements using a particular attribute, right-click on the word 'shared'. To separate the definition for a particular element (to choose a different default value, for instance), select the name of the element from the pop-up menu. A separate entry for that attribute will be created. To avoid separating the definitions, click outside of the pop-up menu.
Data Type	Attributes have much simpler content model choices than elements. You can enter an attribute's data type in the Data Type column by typing it or by clicking the Type button and then choosing a data type from the list. The available data types are described in Table 30.
Constraints	The Constraints column allows you to limit the choices available for attribute values. This column is only applicable if the enumerated type is selected in the Data Types column. In this case, the Edit Enums button loads the enumerations editor (the Enumerations tab of the properties panel), where you can specify a list of possible values (of the specified data type) for the attribute. For more information on constraining attribute values, see Properties Panel.
Use	The Use column lets you indicate how attributes will be used in XML instance documents. Clicking the Select Use button will enable you to select from the following options: • optional — Attribute may appear in an XML instance document, but its use is not mandatory. No value is assigned in the schema, but XML document authors can assign any value to the attribute consistent with its type. • required — Attribute must appear once in an XML instance document. No value is assigned in schema, but XML document authors can assign any type-compatible value. • default — Attribute may appear in an XML instance document, but its use is not mandatory. If it appears, it can have any type-compatible value. If the attribute does not appear, a schema-aware processor will assign the attribute's value to be what you've specified in the Value column. • fixed — Attribute may appear in an XML instance document, but its use is not mandatory. When present, the attribute must have the value you've specified in the Default column. If the attribute does not appear, schema-aware processors will assign the attribute's value to be what you've specified in the Value column.
Value	If the attribute’s usage is designated as default or fixed, enter the default or fixed value in the Value column. Choosing either optional or required and then entering a value in the Value column will produce an error message. Choosing either default or fixed and omitting a value in the Default column will also produce an error.

 

Table 30 Datatypes within a DTD

Datatype	Meaning
ID	The value must be an XML name, beginning with a letter and otherwise composed of letters, digits, hyphens, underscores, and full stop characters. (Colons are prohibited for documents conforming to the Namespaces in XML 1.0 W3C Recommendation.) The value of the attribute must also be unique within the document among all attributes of type ID. ID attributes may never have fixed default values. Only one attribute per element may be of type ID. Typically, attributes containing ID values are named 'id', though this is not required.
IDREF	The attribute value must match the value of an ID attribute of an element contained within the same XML document.
IDREFS	Multiple values of ID attributes may appear, separated by white space, but all must match ID values in the document. (A single ID value is also acceptable.)
ENTITY	The attribute value must match the name of an external unparsed entity declared elsewhere in the document type definition. (Colons are prohibited within the value of this type of attribute for documents conforming to the Namespaces recommendation.)
ENTITIES	Like ENTITY, except that multiple names of unparsed entities may appear with white space separating the values. (Colons are prohibited within the value of this type of attribute for documents conforming to the Namespaces recommendation.)
NMTOKEN	The attribute value must contain letters, digits, periods, dashes, underscores, combining characters or extenders. No other characters (including white space) may appear. (Colons are prohibited within the value of this type of attribute for documents conforming to the Namespaces recommendation.)
NMTOKENS	Like NMTOKEN, except that multiple name values may appear with white space separating the values. (Colons are prohibited within the value of this type of attribute for documents conforming to the Namespaces recommendation.)
enumerated	Provides a list of acceptable values. The word enumerated isn't stated in the declaration. Instead, a list of possible values for the attribute appear in the Constraints area in parentheses, separated by vertical ('or') bars. (value | value).
NOTATION	The NOTATION keyword must be followed by a list of acceptable notation identifiers in the same format - (value | value...) - used for enumerated values. All values provided must have been declared as NOTATIONS elsewhere in the document type definition.

 

DTD data types are not oriented toward data in the sense used by programmers and database developers, but can be useful for describing relationships within documents and for constraining data to a list of acceptable values. If you require stricter, data-oriented data types, consider using Schema resources.

Example: Creating or Editing an Attribute

Attributes are created by declaring an attribute type in the attributes panel or by entering attribute names for an element in the element list of the elements panel.

New attributes entered in the element list of the elements panel are automatically created in the attributes panel with a data type of string.

Creation of an attribute type within the attributes panel consists of several steps. For example, assume you have an element Picture, with the attributes GraphicsType. GraphicsType is an attribute that tells us if a picture is a JPG, TIF, or GIF file.

Here are steps for declaring GraphicsType:

1.	Click on a blank line under the Attributes Name column. Enter the attribute name GraphicsType. Names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods.

2.	Select the cell under the next column heading, Element, in the row for GraphicsType. Since we know this attribute will be used by the element Picture, type in Picture.

3.	Select the cell under the next column heading, Data Type.

An attribute type declaration, by default, sets the data type for an attribute to string. In this example, GraphicsType will be enumerated (that is, it will only ever have the value of JPG, TIF, or GIF).

4.	Click the Type button and select enumeration from the XML Types menu.

Since GraphicsType can be only be a JPG, TIF, or GIF, these values must be entered in the attribute type declaration.

5.	Click on the cell under the column heading Constraints, then click on the Edit Enums button to display the properties panel, with the Enumeration tab active.

6.	In the text box at the top, enter 'JPG' (without quotes), and then click the Add button.

7.	Follow the same procedure to add 'TIF' and 'GIF'.

Figure 59 Enumeration Tab

As you enter values in the Enumeration tab, they are inserted in the Constraints column of the attributes panel. Notice that the JPG, TIF, and GIF entries are separated by the OR indicator ('|').

A default value can be entered for an attribute.

8.	To set the default value of GraphicsType to JPG, tab into the cell under the Use column for the row GraphicsType. Click the Select Use button to display a menu of choices. Choose 'default' from the drop-down menu.

9.	Tab to the Value column and enter the default value, which should match one of the enumerated values.

This completes the declaration for GraphicsType.

Overview Panel

When you choose Schema >View >Overview or click the Overview button on the toolbar, the overview panel loads to the left of the elements panel. The overview panel allows you to control the creation of schemas that use multiple modules, as well as explore the overall organization of your schema. The overview panel's tools let you build schemas from declarations in multiple files, create large composite schemas from sets of smaller ones, enhance reusability and simplify management. Figure 60 illustrates the overview panel with the right button menu activated.

Figure 60 Overview Panel

Overview Tree

The overview panel provides a tree-like overview of the schema structure. Each schema component type is represented by an icon, described in the table below.

Table 31 XML Schema Icons

Icon	XML Schema Component
	element
	attribute
	model group (internal parameter entity)
	attribute group (internal parameter entity)
	XML comment
	schema document
	included schema (external parameter entity)

A right-button menu is provided for each component in the overview tree. From the menu, you can cut, copy, paste or clear a declaration or module (removing it or changing its location in the schema). There is also an option to “Go to” or “Edit” the component, which will take you to an area to edit the selected item.

If the declaration is located in an external schema that has been added to the current schema, a menu option to unlock the module is provided. Before any edits can be made to included declarations (identified by a document icon with a red slash), the included schema must be unlocked. When a module is unlocked, the red line disappears from the document icon. When you are done editing the included declarations, you can right-click on the module and lock it again. .

Any changes made to unlocked declarations of an included schema will be reflected in the included schema as well.

Add Module...Button

The Add Module option of the overview panel allows you to include the declarations from another of your project’s schemas into the schema you are currently building (through an external parameter entity reference). To remove an included schema, right click on the included schema icon and select Clear from the pop-up menu that appears.

Example: Including declarations from another schema

When building a schema, it is often desirable to reuse components already declared in another schema.This example illustrates the steps required to include another schema’s declarations in your schema.

1.	Click the Add Module button of the overview panel.

2.	Browse to and select the schema containing the declaration you would like to use. The included module will appear in the Overview tree, identified by the included document icon.

Figure 61 Overview Tree

Modules can also be added using the Parameter Entities tab of the advanced panel.

3.

The included schema’s declarations now appears in the declaration panels for your current schema and can be used just like any other declaration. The added declarations are not editable by default, however. To edit these declarations, right click the document icon and choose unlock. Be aware, however, that any changes made to the declarations will be reflected in the original document as well.

Properties Panel

When selected from the Schema > View menu or upon clicking the Properties button on the toolbar, the properties panel loads to the left of the elements panel. The properties panel includes three tabs -- Properties, Constraints, and Enumeration. When working with a DTD resource, only the Enumeration tab is applicable. When an attribute is of type enumeration, use the Enumeration tab to create a list of possible values.

Enumeration tab

The Enumeration tab allows you to enumerate allowable values for an attribute. Accordingly, the Enumeration tab becomes applicable when an attribute is declared to be of type enumeration. The Enumeration tab is shown in Figure 62.

Figure 62 Enumerations Tab of the Properties Panel

When an enumeration is applicable, the tab can be accessed by:

•	clicking the Properties button on the Toolbar, and then clicking the Enumeration tab in the properties panel.

•	clicking the Edit Enums button in the Data Types column of the attributes panel

In the text box at the top of the Enumeration tab, enter a value and then click Add. Repeat this procedure for each of the possible values. The values will appear in the list box beneath the text box used for input. You can use the Up and Down buttons to reorder the values in the list. You can also select a value in the list and either Delete it or Replace it with a value entered in the text box at the top. As you edit the enumeration in the Enumeration tab, the current values are reflected in the Constraints column of the attributes panel.

Advanced Panel

When selected from the Schema > View menu, the advanced panel becomes the primary panel for editing. The advanced panel allows you to define or edit parts of a DTD that move beyond the description of document structures. The advanced panel consists of the Parameter Entities tab, the General Entities tab, the Notations tab, and the Processing Instructions tab.

Parameter Entities Tab

When working with a DTD resource, the Parameter Entities tab provides access to internal and external parameter entities definitions. Internal parameter entities are used to implement reusable declarations or text (Schema > Tools > Define Reusable), while external parameter entities are used to support the modular schema architectures provided by the overview panel’s Add Module feature. Users familiar with DTD syntax may prefer to add parameter entities directly through the Parameter Entities tab.

The parameter entities tab is divided into two panels. The top panel is used for internal parameter entities, whose values contain their replacement content directly, while the bottom panel is used for external parameter entities, which contain references to external files that contain content.

Internal parameter entities have only a name and a value. (Entity names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods.) The value must contain either complete declarations (more common in external entities) or fragments of single declarations. Declarations may not cross entity boundaries, though they may contain multiple entities. Entities may also contain entities themselves.

For example, to create an entity named 'shortened' that has the value '(title, paragraph)' - an element content model - the entries shown in Figure 63 would be appropriate.

Figure 63 Creating an Internal Parameter Entity

Once you have created a parameter entity, you can reference it within other declarations. To use parameter entity content, simply reference the entity using the following syntax:

%entityName;

Figure 64 illustrates the use of a parameter entity within a content model.

Figure 64 Referencing a Parameter Entity within a Content Mode

l

External parameter entities have names and references to external resources. External parameter entities must have system identifiers (either a full or relative path name to another DTD in your project) and may optionally have public identifiers as well. An 'Include in DTD' check box is provided that makes it easy to include external modules in your DTDs. If the external DTD contains multiple declarations, you'll want to make sure it gets checked.

Modules that have been added through the overview panel will appear here, and modules added here will appear in the overview panel. When you add a module, its content is downloaded for use in the current schema. The parameter entity declarations for that module will also appear in the parameter entity window, preceded by an icon if the module hasn't been opened for editing in the overview panel. A listing of external parameter entities is shown in Figure 65.

Figure 65 Listing of External Parameter Entities

 

In the System column, you can use the Insert File Name button to browse for and select a file in your project containing the desired declarations.

General Entities

DTDs provide facilities for defining some forms of content as well as document structure. Documents can include this predefined content by reference, allowing schema developers to centralize management of content as well as structure. Typically this approach is used to avoid search-and-replace on content that will be changing, or to include large chunks of 'boilerplate' content within a document.

In the General Entities tab of the advanced panel, the following types of entities can be defined:

•	internal general entities

•	external general entities

•	external unparsed entities

The top panel is used to define internal general entities, while the bottom panel is used to define external general entities and unparsed entities.

Like the other panels, the rows begin with a selector button that can be used to select the entire row for cut, copy, paste, and clear operations. If there is an error in the declarations made in a row, the row selector button will turn red. The column between the selector and the entity name will contain a document icon if the declaration has been included from another file. If it came from another file, it cannot be edited, though it can be copied and pasted into the current file.

The name for an entity is entered and displayed in the Name column. (Entity names must begin with a letter and may contain numbers, underscores, dashes, and full stops -- typically periods).

Internal General Entities

Defining an internal general entity requires only the entry of a name and a value. The value must be plain text or well-formed XML - all start tags in the entity must have end tags and vice versa. Figure 66 illustrates the creation of two internal general entities.

Figure 66 Defining Internal General Entities

Documents using this schema may now include the content defined in the general entity area using entity references, which look like:

&entityName;

The parser strips out the entity references and replaces them with the value of the entity. For example, using the entities described in the figure above,

Our new &productName; (&productNum;) is the finest of its breed.

will become:

Our new Capital 8850 (CXY-8850) is the finest of its breed.

External General Entities

External general entities work very similarly, except that the value isn't given in the declaration. Instead, a reference to another document in your project is provided (either a full or relative path name), and the contents of the referenced document are used as the value for substitution. Like the value of an internal entity, all markup within the referenced file must be well-formed. Optionally, a public identifier (used in some SGML environments) may be provided. The notation column should be left blank for an external general entity. Figure 67 illustrates the creation of an external general entity.

Figure 67 Defining an External General Entity

External general entities are referenced from documents the same way that internal general entities are referenced -- using the &entityName; syntax. In this case, &play; would reference the XML document 'othello.xml' and include it in a document.

In the System column, you can use the Insert File Name button to browse for and select a file in your project containing the desired content.

External Unparsed Entities

The last kind of entity that can be created in the general entities tab is the unparsed external entities. Unparsed entities reference non-XML content, like graphics files or data. Documents reference unparsed entities through the use of attributes of type ENTITY or ENTITIES. To create an unparsed entity, provide the same information as would be provided for an external general entity (name, system identifier, optional public identifier), but also provide a notation in the Notation column to identify the file type that is being referenced. This notation must be declared on the Notations tab. The 'myGraphic' unparsed entity shown below in Figure 68 is an example of an unparsed entity.

Figure 68 Defining an External Unparsed Entity

Notations

Notations allow you to describe a new data type or file type. The description involves a name for the type and a link to more information on the type or to programs that can process the type. For example, the notations declared in Figure 69 provide information on ISO8601 dates and times, and Java integers. Either could be used for a data type and will appear as an option in the type menus that appear in the elements panel and attributes panel.

Figure 69 Notations

Each notation is listed in a row of the panel. Information associated with each notation appears in columns across the panel and includes the following (from left to right).

Table 32 Notations in Panel

Column	Description
Row Selector/Error Indicator	This column allows you to modify the row and detect errors in the declaration. See Common Columns In Tables for more information about this column.
Included Document Indicator	This column indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables for more information about this column.
Name	Enter or edit the name of the notation.
Location	Enter the URL that will serve as the system identifier for the notation. System identifiers are not required for notations, though at least one identifier (system or public) must appear. System identifiers may point to standards describing the content or to programs that can actually process it. Note: Use the Insert File Name button to browse for and select a file in your project containing the desired content.
Public Name	Enter a public identifier for the notation. Public identifiers are not required for notations, though at least one identifier (system or public) must appear. Public identifiers should match the public identifiers standards authors provide for their specifications to ensure uniformity across documents from different sources.

Notation information is processed by the parser only minimally; the applications that process your documents will need to provide an extra level of support to interpret notations.

Processing Instructions

Processing instructions are a relatively free-form way to include extra information about your schema for an application to use.

Each processing instruction is listed in a row of the panel. Information associated with each processing instruction appears in columns across the panel and includes the following (from left to right).

Table 33 Processing Instruction

Column	Description
Row Selector/Error Indicator	This column allows you to modify the row and detect errors in the declaration. See Common Columns In Tables for more information about this column.
Included Document Indicator	This column indicates whether the declaration comes from the file being edited or from an external schema. See Common Columns In Tables for more information about this column.
Target	Enter the target name. The target needs to be a name beginning with a letter and possibly containing numbers, underscores, dashes, and periods.
Instruction	Enter the instruction for the processor. The format for the instruction is up to you, though it may not contain the sequence ?>, which ends a processing instruction,

Schema Properties Panel

When selected by way of the Schema > View menu, the schema properties panel is displayed. The schema properties panel provides a count of the different type of components used to build the DTD. (This information is also found on the Statistics tab of the configuration panel).

Errors Panel

When selected by way of the Schema > View menu or upon clicking the Errors button on the toolbar, the errors panel appears between the active editing panel and the configuration panel. The errors panel displays errors found when a new DTD is loaded, as well as errors detected throughout the editing process.

The errors panel indicates the total number of errors and provides a list of errors and details about the errors in this panel. Clicking on the error message will take you to the source of the error.

To update error information in the DTD after correcting an error, it's good practice to check for errors again by way of the Check for Errors button on the top of the panel.

A red selector button in a declaration panel is indicative of an error.

Notes Panel

The raw declarations in your schemas are very useful for parsers processing your document, but are rarely sufficient for other humans who need to read and make sense of your schema. Adding notes helps those who use and maintain your schema to understand your schema designs, and can be a critical tool for keeping groups of developers working on the same or related schemas in sync.

The notes panel provides an area where you can add schema level documentation to your schema as well as document individual declarations and preview their source. When selected by way of the Schema > View menu, the notes panel appears between the active editing panel and the configuration panel.

Use the button in the upper right-hand corner of the notes panel to indicate whether you are interested in working with declaration-level notes (the default view) or notes about the schema as a whole. To view or edit notes for the schema as a whole, click Show Document. (The name of the DTD will appear in the upper left-hand corner of the panel.) To toggle back to the default, declaration-level view, click 'Show Selected Declaration'. (The the name of the declaration will appear in the upper left-hand corner of the panel.)

When the notes panel reflects the selected declaration, three tabs are available:

Table 34 Notes Panel in Selected Declaration

Tab	Description
All Notes	Displays all the notes entered for the selected declaration. Notes cannot be edited within this tab.
Usage Notes	Use this tab to associate a new note with the selected declaration. In the source code, the note will appear within the selected declaration, as an XML comment: <!--usage note-->
Source Preview	Displays the source code for the selected declaration.

When the notes panel reflects the document as a whole, two tabs are available:

Table 35 Notes Panel

Tab	Description
All Notes	Displays all the top-level notes. Notes cannot be edited within this tab.
Usage Notes	Use this tab to associate a new note with the schema. In the source code, the note will appear as an XML comment above the first declaration.

Source Panel

When selected by way of the Schema > View menu or upon clicking the Source button on the toolbar, the source panel becomes the primary panel for editing. The source panel allows you to edit the source code of your DTD directly. If you're comfortable with DTD syntax, editing your declarations directly may occasionally be useful or even convenient. Even if you don't want to edit your DTD directly, the source panel provides another way to examine your declarations.

To make the other panels reflect the changes you've made, click Reparse at the top of the panel. Any errors found upon reparse will be listed in the errors panel.

Copyright © TIBCO Software Inc. All Rights Reserved