Most of the topics in this guide focus on the DTD. The only exception is this initial topic, which explains the structure of the guide itself.
Terminology
Some terms are used in this guide that require clarification or precise definition, including abbreviations, names, user guide concepts, and specific DTD features.
The author of an article (from a journal) is distinguished from the tagger (working for a supplier) who applies XML markup to the raw text. The term "we" refers to Taylor & Francis personnel and "you" refers to the tagger or supplier of services or software that assist with article tagging.
In the TFJA (Taylor & Francis Journal Article) DTD, each component of the document model described by the DTD is an XML element or an XML attribute.
When discussing elements, a reference is sometimes made to the "kind" of element, in terms of whether it is a container of other element structures (such as an entire article, or the metadata section of an article), or directly contains a block of text (such as a title), or isolates an inline fragment of such a block (such as a superscript letter or digit). An empty element (such as a page-break indicator) has no content at all (and may be inline or between blocks).
When discussing element and attribute declarations (their precise formulation in the DTD), the term shared attribute is used to describe an attribute that alone, or as part of a group of attributes, is included in a number of element declarations. Similarly, when a number of elements have the same or similar content models, the term shared content model is used to describe a re-usable model fragment.
Topics
The guide begins with a series of topics, mostly related to features and concepts relevant to the DTD (though the topic you are reading now is an exception). Some topics discuss issues that are strictly speaking beyond the scope of a DTD, but are nevertheless important to the accurate production or processing of articles that conform to the DTD. The remaining topics take a "high-level" view of the document model described by the DTD, often discussing how a number of elements cooperate (or compete) to solve a particular problem.
Element and Attribute Descriptions
Every element in the DTD has a desciption dedicated to it that includes examples and descriptions of each of the attributes that are unique to that element. These descriptions can be accessed in various ways, including via cross-references. However, exploration often begins via an index of the elements. Two indexes are provided: one listing the elements alphabetically, the other showing groups of related elements within a hierarchy of similar concepts.
Every attribute that is shared across multiple attributes is described in a single place to avoid repetition and to highlight the significance of such attributes. An alphabetically sorted index of these attributes is provided.
Tree Diagrams
One part of an element description takes the form of a diagram that requires some explanation to interpret properly.
The content model of each element in the DTD is explained in the description, and is also defined precisely by including the DTD fragment of its declaration. However, neither approach targets the user who requires a precise understanding but does not understand the syntax of DTD declarations. For this reason, a third approach is included that combines the precision of the DTD with a representation that is visually much easier to interpret. Each element description includes a "tree-diagram" that shows the child elements allowed, and any constraints on their ordering and number of occurrences allowed. In an interactive publication of this user guide, the names of the elements may also be highlighted to indicate that they also act as hypertext links to their definitions.
When the child elements must be used in a specific order, the names are presented vertically with a line between them:
--+(sequence)
|
FirstElement
|
SecondElement
|
ThirdElement
When one element from a set of alternative elements must be chosen, the elements in the set are shown as follows:
--+(choice)
|
|-- MaybeThisElement
|
|-- OrMaybeThisOne
|
|-- ThirdAlternative
Content models may involve sequences within choices, choices within sequences, and other nesting options, up to any number of levels. At each level, the vertical line is indented. In the following example, there is a choice within a sequence:
--+(sequence)
|
FirstElement
|
|--+(choice)
| |
| |-- FirstChoice
| |
| |-- SecondChoice
|
LastElement
Sometimes, a choice group will apear within another choice group for no obvious reason. The actual reason is usually that the inner choice group was defined in a shareable content model fragment, and in this case the title of this shared fragment is also shown:
--+(choice)
|
|-- FirstChoice
|
|--+ (choice) [Re-used Model]
| |
| |-- CommonChoiceOne
| |
| |-- CommonChoiceTwo
|
|-- ThirdChoice
In the previous sequence example above, both of the elements in the sequence group are required, and the option group is also a required component of the sequence group (the chosen element from this group must appear between "FirstElement" and "LastElement"). But individual elements and entire sequence/choice groups may actually be optional, repeatable or both. This information is provided in the diagrams. The labels "(optional)", "(repeatable)" and "(optional and repeatable)" are placed next to the names of elements with these occurrence constraints. Similarly, an entire sequence of choice group may include these terms to show that they are optional or repeatable (or both):
--+(repeatable sequence)
|
FirstElement (repeatable)
|
SecondElement (optional)
|
ThirdElement (optional and repeatable)
Finally, some information about the content of the child elements is provided. All of the examples above would be empty elements. In other scenarios, the kind of content is explained as follows:
--+(repeatable sequence)
|
TextContent -- TEXT
|
ElementContent (optional) -- (elements)
|
MixedContent -- (TEXT and elements)
The DTD
The last major section of this user guide is a complete copy of the DTD. Electronically published renditions of this section include hypertext links between the DTD declarations of elements, and the references to these definitions from within the content models of other element declarations (as well as to the user guide descriptions of these elements).