One Document Does It All: Documentation for an ODD system for tag set construction
[Cache (HTML display format) from http://www.tei-c.org/Vault/ED/edw29.sgm; please use this canonical URL/source if possible.]
<!DOCTYPE TEI.1 system 'tiny.dtd' [
<!ENTITY % dtdmods system 'odd.dtd'>
%dtdmods;
<!ENTITY ref.ca system 'comadd.odd' >
<!ENTITY ref.oa1 system 'oddadd1.odd'>
<!ENTITY ref.oa2 system 'oddadd2.odd'>
<!ENTITY ref.ort system 'oddreft.odd'>
<!ENTITY ref.ore system 'oddrefe.odd'>
<!ENTITY ref.orc system 'oddrefc.odd'>
<!ENTITY ref.ora system 'oddrefa.odd'>
<!ENTITY ref.om system 'oddmisc.odd'>
]>
<TEI.1>
<header>
<filDescr>
<citation>C. M. Sperberg-McQueen and Lou Burnard,
<title.p>One Document Does It All: Documentation for an ODD system
for tag set construction.</title.p>
TEI ED W29.
Unpublished; for testing and development. November-December 1991.
</citation>
<source><citation>No source; created in m-r form.</citation>
</source>
</filDescr>
<revHist>
<list>
<item>26 Mar 92 : CMSMcQ : minor reworking, case fixes
<item>25 Mar 92 : CMSMcQ : fixes after successful printing
<item>18 Mar 92 : CMSMcQ : continued quick revs. Skipped past detailed
discussion of ref crystals without completing them, reached
ca. line 840 (detailed account of Odd.dtd).
<item>17 Mar 92 : CMSMcQ : continued quick revs, add tag lists in appx
<item>8 Mar 92 : CMSMcQ : Quick revs, hoping to make useful for others.
Got to about line 300.
<item>8 Jan 92 : CMSMcQ : Upgrade to new Odd.dtd.
<item>29 Dec 91 : CMSMcQ : Further expansion.
<item>14 Dec 91 : CMSMcQ : Expand to broader overview document to help
TEI participants who must read ODD files.
<item>25 Nov 91 : CMSMcQ : Made file (as ODDDOC.P2X)
</list>
</header>
<text>
<front>
<tPage>
<tp.title>One Document Does It All:
Documentation for an ODD System of Tag Set Construction
<tp.auth>C. M. Sperberg-McQueen
<tp.auth>Lou Burnard
<tp.publ>Text Encoding Initiative: Document TEI ED W29
<tp.date>14 November 1991
</front>
<body>
<!>
<div1 name='Section' n=1><head>Introduction</head>
<p>The Odd (<soCalled>One Document Does it all</soCalled>) system is a
prototype SGML DTD-generator developed to aid in the production of
version 2 of the Text Encoding Initiative's <title>Guidelines for Text
Encoding and Interchange</title> (TEI P2). It is modeled very directly
on Donald Knuth's WEB system,
<note><p>WEB is distributed with the public-domain code of TeX and
MetaFont, which are written in WEB. See
<citation>Donald E. Knuth, <title.p>Literate Programming</title.p>
(submitted to <title>The Computer Journal</title> [n.d.])</citation> and
<citation>[Donald Knuth], <title>The WEB System of Structured
Documentation</title> [WEB User Manual], Stanford Computer Science
Report CS980 (September 1983).</citation> Both are
distributed with (at least some versions of) TeX.</p></note>
but substitutes TEI SGML tags for TeX as the document formatting
language and SGML DTDs for Pascal as the programming language.
<p>In general, Odd works like this: in a single document (the Odd
document) the user describes an SGML-based markup language or tag set,
using the Odd tag set. The Odd document is then used by three
distinct processors to produce three very different kinds of output:
<list>
<item>One processor (OddP2X) produces SGML-tagged prose documentation
for the tag set, embedding fragments of the DTD within it (as Pascal
code is intermingled with prose in the Web system); it corresponds to
Knuth's <term>Weave</term> processor.
<item>A second processor (OddRef) produces SGML fragments to be included
in an alphabetic reference manual of the tags, attributes, and other
items in the markup language. OddRef has no direct correspondence in
WEB, though it is closer to <term>Weave</term> than to
<term>Tangle</term>.
<item>The third processor (OddDtd) produces an SGML DTD for the markup
language; it corresponds to Knuth's <term>Tangle</term> processor.
</list>
<p>A fourth processor (DtdOdd) has been developed which makes the
production of Odd documents easier: it takes a conventional DTD as
input and produces a set of partially completed tag documentation
crystals; it can be used as the first step in preparing Odd
documentation for existing tag sets.
<p>In this document, we describe the types of files used by the Odd
system for input and output, the specialized tags provided by the Odd
DTDs, the DTDs and their structure, and the processors which work with
them. An appendix includes a brief description of the tags in Tiny.dtd,
the base tag set. The document in its current form is intended for
internal use within the TEI and assumes either a profound familiarity
with SGML and the TEI DTDs or a great tolerance for unfamiliar technical
material.
<div1 n=2><head>Types of Files</head>
<p>The Odd system uses and produces several types of files, with the
following file extensions (common across all systems):
<list type=gloss>
<label>odd <item>the main document type, in the Odd tag set, input for
all three processors
<label>p2x <item>prose documents in the P2X prose tag set
<label>ref <item>reference material on the tags of the markup language,
which may be included within P2X documents or processed separately as a
Ref document
<label>dtd <item>normal SGML DTDs, produced by OddDtd
</list>
These are described in more detail below.
<div2 name='Section'><head>Odd Files</head>
<p>Odd is the main document type: it serves as input for all processors
and contains all the information used in defining the tag set.
<p>An Odd document uses, for the most part, conventional SGML tags for
prose documents; because the Odd tags themselves are defined as an
<term>additional tag set</term>, they are in principle usable with
multiple bases, and any standard tag set for prose could be taken as the
base tag set for Odd documents. At present (March 1992) the Odd system
uses a prose base called Tiny.dtd, based on TEI P1 by way of the
<soCalled>toy</soCalled> DTDs prepared for TEI workshops during 1991.
<note place=foot>The tags present in Tiny.dtd are described briefly in
an appendix to this document.</note>
When TEI P2 is completed we expect to modify the Odd system to use TEI
P2's tag set as its base.
<p>The Odd DTD comprises additional tags to be used in what is otherwise
a normal document using the Tiny tag set. Odd files should use the Odd
DTD, which is invoked thus:
<eg>
<![ CDATA [
<!DOCTYPE TEI.1 system 'Tiny.dtd' [
<!ENTITY % dtdmods system 'Odd.dtd'>
%dtdmods;
]>
]]>
</eg>
The Odd DTD keeps its extensions to the base prose tag set rigorously
separate and visible, and thus serves as an example of the method of DTD
extension envisaged by TEI ML W43 and TEI P1 chapter 8.
<p>This document in its current form focuses largely on the tags of the
Odd DTD. Those of the other DTDs (P2X and Ref) are very much the same,
differing mostly in whether certain elements are optional or required.
<div2><head>P2X Files</head>
<p>P2X files contain prose documentation of the tag set; they will
ultimately conform to TEI P2 but use extensions --- hence the file type
of <cited>P2X</cited> (<gloss>P2 extended</gloss>), which keeps these
files distinct from files vanilla-conformant with TEI P2, which we
expect to use the filetype <cited>TEI</cited>. Since P2 is not ready
yet, P2X files, like Odd files, currently use not P2 but the
general-purpose prose tag set defined in Tiny.dtd. P2X files should use
P2x.dtd, which is invoked thus:
<eg>
<![ CDATA [
<!DOCTYPE TEI.1 system 'Tiny.dtd' [
<!ENTITY % dtdmods system 'P2x.dtd'>
%dtdmods;
]>
]]>
</eg>
P2X, like Odd, keeps its extensions separate from the base (here
Tiny.dtd) and serves as an example of tag set extension as envisaged in
TEI P1 and ML W43. The P2X DTD is so constructed that Ref files may be
included within P2X documents.
<div2><head>Ref Files</head>
<p>Ref files contain one or more <gi>tagDoc</gi>, <gi>attDoc</gi>,
<gi>classDoc</gi>, and <gi>entDoc</gi> elements. Ref files are the
output of the <term>OddRef</term> processor and the filetype should not
be used for other files. If Ref files are to be processed as
independent documents, they should use Ref.dtd, but normally Ref files
are included within P2X files for processing.
<div2><head>DTD Files</head>
<p>DTD files contain DTD fragments; when the tag set is prepared using
Odd, the DTD files are created by running the OddDtd processor on an Odd
file. DTD files will contain element, attList, and comment declarations
in the usual syntax. The element and attList declarations are enclosed
in marked sections so that individual tags in the set can be
conveniently turned off or redefined by users of the markup language; in
the future names may also be replaced by entity references as described
in TEI P1 chapter 8. At the moment, we expect to perform the
name-indirection by post-processing the DTDs, not by modifying OddDtd.
<!>
<div1 n=3><head>Special Tags in Odd and P2X Documents</head>
<p>To the base tag set used, the Odd system adds (1) specialized tags to
appear in running prose, which mark tag names, attribute names, sample
tags and lists of tag descriptions which should echo the descriptions in
the reference manual, and (2) structures (reference crystals) to provide
the specialized information needed to print an alphabetical reference
list of tags and attributes. The following two sections describe these
two classes of tag. Note that some tags are specific to Odd documents
or P2X documents, while others are common to both types.
<div2><head>Tags for Prose Documentation</head>
<!-- desc, list, exx, dtdFrag -->
<div3 id=od.names name='section'>
<head>Phrase-level Tags for SGML Names</head>
<p>SGML tag set documentation requires frequent mention of generic
identifiers, attribute names, and special attribute values. These are
all technical terms and could be tagged with <gi>term</gi>, but we
distinguish them so they can be typeset differently and generate
distinct types of index entries.
<p>Odd and P2X documents both use the following specialized tags:
<list type=gloss>
<label><gi>tag</gi></label>
<item>marks SGML start-tags and end-tags appearing in prose.</item>
<label><gi>gi</gi></label>
<item>marks a generic identifier for an SGML element type.</item>
<label><gi>att</gi></label>
<item>marks attribute names appearing in prose.</item>
</list>
All of these elements can carry the following attribute:
<list type=gloss>
<label><att>tei</att></label>
<item>indicates whether the name marked is a TEI name or not
Values:
<list type=gloss>
<label><term>yes</term></label>
<item>the item is a TEI name and should be indexed as such</item>
<label><term>no</term></label>
<item>the item is not a TEI name and should not be indexed</item>
</list></item>
</list>
<p>No specialized tag is provided for defined attribute values; they
should be tagged as technical terms. Extended examples of SGML tag
usage should be enclosed in <gi>eg</gi> tags; generally the contents of
the <gi>eg</gi> element should be a CDATA marked section. (<gi>eg</gi>
is not defined as a <term>CDATA</term> element, however, because
end-tags for open elements are recognized within CDATA elements; if a
CDATA element within a paragraph contains a <tag>/p</tag> tag, it will
be recognized as the end-tag for the enclosing paragraph. This
interferes too often with examples to make CDATA elements useful for
examples of SGML tagging.)
<p>As an example of these tags' use, consider the parenthetical remark
in the previous paragraph, which is tagged thus:
<eg>
<![ CDATA [
(<gi>eg</gi> is not defined as <term>CDATA</term>, however,
because end-tags for open elements are recognized within
CDATA elements; if a CDATA element within a paragraph
contains a <tag>/p</tag> tag, it will be recognized as the
end-tag for the enclosing paragraph. This interferes too
often with examples to make CDATA elements useful for
examples of SGML tagging.)
]]>
</eg>
<p>These tags are defined formally as follows:
<eg id=cadd1>
<![ CDATA [
<!-- 3.1.1: Phrase-Level Tags for SGML Tags and Names -->
<!ENTITY % a.teiTerm '
tei (yes | no) no ' >
<!ELEMENT tag - O (#PCDATA | gi | att)* >
<!ATTLIST tag %a.global;
%a.teiTerm; >
<!ELEMENT gi - O (#PCDATA) >
<!ATTLIST gi %a.global;
%a.teiTerm; >
<!ELEMENT att - - (#PCDATA) >
<!ATTLIST att %a.global;
%a.teiTerm; >
]]>
</eg>
<!-- Here embed the reference crystals for this section. -->
<!-- Revisions: -->
<!-- 27 Mar 92 : MSM : normalize case of identifiers -->
<!-- 8 Jan 92 : MSM : upgrade to new Odd.dtd -->
<!-- ComAdd.ref: reference crystals for tags in ComAdd.dtd: -->
<!-- tag, gi, att, and the class teiTerm. -->
<!-- *************************************************** tag -->
<!-- *************************************************** gi -->
<!-- *************************************************** att -->
<!-- ************************************************ teiTerm -->
<div3 id=od.tagl><head>Tag Lists with Descriptions</head>
<p>The normal method of introducing tags in TEI documentation is to
provide a single paragraph introducing a set of related tags, list the
tags and attributes involved, provide examples, and end with a DTD
fragment showing how the tags are defined. The following tags are
provided for the lists of tags and attributes:
<list type=gloss>
<label><gi>tagList</gi></label>
<item>marks a list of tags to be inserted into the prose documentation,
formatted as a glossary list.
Attributes include:
<list type=gloss>
<label><att>style</att></label>
<item>indicates layout style to use for tag description list
Values:
<list type=gloss>
<label><term>one-line</term></label>
<item>each <gi>tagDesc</gi> generates list item with the gi as the term and the one-line <gi>desc</gi> from the <gi>tagDoc</gi> element as the description.</item>
<label><term>long</term></label>
<item>undefined; present only as stub and reminder that other styles may be desired later.</item>
<label><term>green</term></label>
<item>undefined reminder that other styles may be desired later.</item>
</list></item>
</list>
</item>
<label><gi>tagDesc</gi></label>
<item>indicates that a given gi should be included at this point in a
<gi>tagList</gi>.
Attributes include:
<list type=gloss>
<label><att>tagDoc</att></label>
<item>indicates which gi should be included in a tag list.</item>
<label><att>atts</att></label>
<item>indicates which attributes of the element, if any, should be mentioned in the description of the tag.</item>
</list>
</item>
<label><gi>adList</gi></label>
<item>marks a list of attributes and their descriptions.
Attributes include:
<list type=gloss>
<label><att>classDoc</att></label>
<item>specifies the element class for which the attributes in the list are defined.</item>
<label><att>atts</att></label>
<item>indicates which attributes of the class, if any, should be included in the list.</item>
</list>
</item>
</list>
<p>In print format, both <gi>tagList</gi> and <gi>adList</gi> should be
formatted like a definition list. In a <gi>tagList</gi>, each
<gi>tagDesc</gi> generates the tag's GI (in angle brackets, bolded) as
the term, and the element's one-line description (from the <gi>desc</gi>
element in the <gi>tagDoc</gi> element) as the definition. Embedded
lists of attributes may also occur within any entry for a GI; the
<att>atts</att> attribute specifies which attributes defined for an
element should be included in the embedded list. (The default is none.)
In P2X files, <gi>tagList</gi> and <gi>tagDesc</gi> do not occur: the
OddP2X processor translates them into glossary lists, as shown below.)
<p>As examples of the use of these tags, consider the introduction of
the phrase-level tags for SGML names in the preceding section, which was
tagged thus:
<eg>
<![ CDATA [
<p>Odd and P2X documents both use the following
specialized tags:
<tagList>
<tagDesc tagDoc='tag'>
<tagDesc tagDoc='gi'>
<tagDesc tagDoc='att'>
</tagList>
All of these elements can carry the following attribute:
<adList classDoc='teiname' atts='tei'>
]]>
</eg>
<p>The P2X equivalent of this is as follows:
<eg>
<![ CDATA [
<!-- substitute real OddP2X output when you can -->
<list type=gloss>
<label><gi>tag</gi></label> <item> ...
<label><gi>gi</gi></label> <item> ...
<label><gi>att</gi></label> <item> ...
</list>
]]>
</eg>
<note>The file P2xAdd.dtd does actually define a <gi>tagList</gi>
element for P2X documents, but it is not used by OddP2X at this
writing (18 March 1992).</note>
<p>These elements are defined thus:
<eg id=oadd1>
<![ CDATA [
<!-- 3.1.2: Tags for Lists of Tags -->
<!ELEMENT tagList - - (tagDesc+) >
<!ATTLIST tagList %a.global;
style (long | one-line | green)
one-line >
<!ELEMENT tagDesc - O EMPTY >
<!ATTLIST tagDesc %a.global;
tagDoc IDREF #REQUIRED
atts CDATA #IMPLIED >
<!ELEMENT adList - O EMPTY >
<!ATTLIST adList %a.global;
classDoc CDATA #REQUIRED
atts CDATA #IMPLIED >
]]>
</eg>
<!-- reference crystals for tagList, tagDesc, adList in oddadd1.odd -->
<!-- OddAdd1: reference crystals for part of OddAdd.dtd: -->
<!-- tagList, tagDesc, adList. -->
<!-- This file is part of Odd.odd. -->
<!-- Revisions: -->
<!-- 26 Mar 92 : CMSMcQ : minor presentation changes -->
<!-- 21 Mar 92 : CMSMcQ : correct classes: no NIL class -->
<!-- 18 Mar 92 : CMSMcQ : minor revisions, checking -->
<!-- 8 Jan 92 : CMSMcQ : made file. -->
<!-- *********************************************** tagList -->
<!-- *********************************************** tagDesc -->
<!-- *********************************************** adList -->
<!-- adList: marks a list of attributes belonging to a class of
elements; in the documentation, this will be formatted like a definition
list. -->
<!-- ************************************************* adList -->
<!-- ******************************************************** -->
<div3 id=od.dtdf><head>Tags for Embedded DTD Fragments</head>
<p>For reference manuals, at least, it is important not merely to
describe the tags of a markup language in prose: the reader must be
able to consult the formal definitions of the tags as well. In order to
exhibit clearly the logical relationships among related tags, it is
useful to be able to embed DTD fragments in a running prose commentary.
(Otherwise, the user would have to consult the element and
attribute-list declarations in the alphabetical reference list; not a
convenient method of understanding a group of tags which conceptually go
together.) Indeed, the Odd system assumes that the entire DTD defining
the tag set will be reproduced, not necessarily in order, in the DTD
fragments included in the documentation. (In this, the influence of Web
is particularly clear.)
<p>The tags provided for this purpose are these:
<list type=gloss>
<label><gi>dtdFrag</gi></label>
<item>encloses a schematic representation of a portion of a DTD within
which special elements represent different types of declaration.
Attributes include:
<list type=gloss>
<label><att>file</att></label>
<item>specifies which DTD file the DTD fragment belongs in.</item>
<label><att>contin</att></label>
<item>identifies the previous DTD fragment continued by the current one, if any.</item>
</list>
</item>
<label><gi>tagDecl</gi></label>
<item>indicates that the element and attribute list
declarations for a given element type logically belong here.
Attributes include:
<list type=gloss>
<label><att>tagDoc</att></label>
<item>indicates which element's declarations appear at this location by pointing at the <gi>tagDoc</gi> for that element.</item>
</list>
</item>
<label><gi>entDecl</gi></label>
<item>indicates that an entity declaration belongs at this point in a
DTD fragment.
Attributes include:
<list type=gloss>
<label><att>entDoc</att></label>
<item>points at the reference crystal for this entity declaration.</item>
</list>
</item>
<label><gi>claDecl</gi></label>
<item>indicates that a parameter entity declaration defining an element
class logically belongs at this point in a DTD fragment.
Attributes include:
<list type=gloss>
<label><att>classDoc</att></label>
<item>points at the <gi>classDoc</gi> crystal for the class in question.</item>
<label><att>type</att></label>
<item>indicates whether entity is for model groups or attribute lists.
Values:
<list type=gloss>
<label><term>model</term></label>
<item>entity is for model groups.</item>
<label><term>atts</term></label>
<item>entity is for attribute list declarations.</item>
</list></item>
</list>
</item>
<label><gi>peRef</gi></label>
<item>indicates that a parameter entity reference logically belongs at
this point in the DTD.</item>
<label><gi>dtdRef</gi></label>
<item>indicates that the contents of a distinct <gi>dtdFrag</gi> element
logically belong here.
Attributes include:
<list type=gloss>
<label><att>target</att></label>
<item>points at the <gi>dtdFrag</gi> which logically belongs here.</item>
</list>
</item>
<label><gi>commDecl</gi></label>
<item>indicates that a comment declaration belongs at this point in a
DTD fragment, with the same contents as the element.</item>
</list>
Their meanings and usage are discussed below.
<p>In the simplest and most common case, the <gi>dtdFrag</gi> element
contains a set of <gi>tagDecl</gi> elements which are replaced in the
output with the element declaration and attribute list declaration for
the element. The tag's generic identifier and its element declaration
are copied directly from the <gi>tagDoc</gi> whose <att>id</att> is
given as the value of the <gi>tagDecl</gi> <att>tagDoc</att> attribute.
The <att>id</att> should usually be the same as the generic identifier,
or the first eight characters of it, but may not be, if more than one
<gi>tagDoc</gi> has the same generic identifier (as for <gi>div1</gi> in
prose texts, verse texts, drama texts, and dictionaries).
<p>In more complicated cases, the <gi>dtdFrag</gi> may also contain
entity declarations (<gi>entDecl</gi>s), parameter entity declarations
for element classes (<gi>claDecl</gi>s), parameter entity references
(<gi>peRef</gi>s), references to other DTD fragments (<gi>dtdRef</gi>s),
and SGML comments (<gi>commDecl</gi>s). Each of these except
<gi>commDecl</gi> is empty and must point at an associated reference
document crystal. N.B. the content model for <gi>dtdFrag</gi> thus
tightly constrains the form taken by Odd-generated DTDs. It is not
possible in Odd as currently implemented, for example, to include
notation declarations in a DTD.
<p><gi>entDecl</gi> indicates that a general or parameter entity
declaration goes in the DTD at this point. The name and entity text of
the entity declaration are copied from the appropriate <gi>entDoc</gi>,
indicated by the <att>entDoc</att> attribute on the <gi>entDecl</gi>
tag.
<p>For example, to declare an external file containing entity
declarations, which will be referred to somewhere in the DTD, and to
declare the entity <term>TEI</term> with the expansion <q>Text Encoding
Initiative</q>, a DTD fragment should read, in part:
<eg>
<![ CDATA [
<entDecl entDoc = EntDecs>
<entDecl entDoc = teient>
]]>
</eg>
<p>The document should also contain entity document crystals which
define these entities (see below).
<p>A <gi>claDecl</gi> indicates that a parameter entity reference
defining an <term>element class</term> belongs in the DTD at this point.
(For discussion of element classes, see the examples below and the
discussion of <gi>classDoc</gi> in section <xref type=div3
target=o.cladoc>.) The <att>classDoc</att> attribute points at the
relevant <gi>classDoc</gi> crystal; the <att>type</att> attribute
indicates whether the parameter entity is to contain a list of all
members of the class (for use in content models) or a set of attribute
declarations common to all elements in the class (for use in attribute
list declarations). If the <att>type</att> attributes on the
<gi>claDecl</gi> and <gi>classDoc</gi> elements disagree, the behavior
of the processors is undefined. (They should issue a warning, but this
has not been implemented yet.)
<p>The entity declarations generated by a <gi>claDecl</gi> element use
entity names constructed from the name of the element class: the name
of the class, prefixed by <q>m.</q> or <q>x.</q> for model-group
entities and by <q>a.</q> for attribute-list entities. The entity text
used in the declarations is generated from the reference crystals as
well. For model-group entities, two entity declarations are generated:
the entity text for the first (with the <q>x.</q> prefix), is the empty
string; for the second (with the <q>m.</q> prefix) the entity text is a
list of members of the class, separated by vertical bars and preceded by
a reference to the first entity. For attribute-list entities, the
entity text is a series of attribute definitions generated from the
<gi>attList</gi> structure within the <gi>classDoc</gi> crystal.
<p>For a class called <q>crystal</q>, for example, a <tag>claDecl
classDoc=crystal type=model</tag> will cause OddDtD and OddP2X to
generate two entity declarations of the form
<eg>
<![ CDATA [
<!ENTITY % x.crystal '' >
<!ENTITY % m.crystal '%x.crystal; ... ' >
]]>
</eg>
where the ellipsis is filled with the names of members of the class.
The <q>x.</q> entity is provided to allow users to add new elements to
the class simply by defining a new meaning for that entity within their
DTD subset. To add the new user-defined elements <gi
tei=no>axiom</gi> and <gi tei=no>theorem</gi> to a tag set, and
allow them to appear anywhere that <soCalled>crystals</soCalled> can
appear the user's document would include the following lines within the
DTD subset:
<eg>
<![ CDATA [
<!ENTITY % x.crystal 'axiom | theorem | ' >
<!ELEMENT axiom - - (#PCDATA) >
<!ELEMENT theorem - - (#PCDATA) >
]]>
</eg>
<p>For attributes shared among members of a class, a <tag>claDecl
classDoc=crystal type=atts</tag> will cause OddDtD and OddP2X to
generate an entity declaration of the form
<eg>
<![ CDATA [
<!ENTITY % a.crystal ' ... ' >
]]>
</eg>
<p>Elements are assigned to classes by the values given to the
<gi>tagDoc</gi> crystal's <gi>classes</gi> element, as described below
in section <xref target = o.tagDoc>. If, for example, the tag
documentation for <gi>emph</gi> and <gi>highlighted</gi> elements
assigned classes as follows:
<eg>
<![ CDATA [
<tagDoc id=emph> ...
<classes names='soup phrases rhet'> ...
</tagDoc>
<tagDoc id=highligh> ...
<classes names='soup phrases typogr'> ...
</tagDoc>
<classDoc id=soup><class>soup</class> ... </classDoc>
<classDoc id=phrases><class>phrases</class> ... </classDoc>
<classDoc id=rhet><class>rhetorical</class> ... </classDoc>
<classDoc id=typogr><class>typographic</class> ... </classDoc>
]]>
</eg>
then something like the following <gi>claDecl</gi>s should appear in
some <gi>dtdFrag</gi> element:
<eg>
<![ CDATA [
<claDecl classDoc=rhet type='model'>
<claDecl classDoc=typogr type='atts' >
<claDecl classDoc=soup type='model'>
]]>
</eg>
which would in turn generate (in the OddDtd processor) something like:
<eg>
<![ CDATA [
<!ENTITY % x.rhetoric '' >
<!ENTITY % m.rhetoric '%x.rhetoric; emph | ...'>
<!ENTITY % a.typographic
'font CDATA #REQUIRED
size NUMBER #REQUIRED'>
<!ENTITY % x.soup '' >
<!ENTITY % m.soup '%x.soup; emph | highlighted | ...'>
]]>
</eg>
<p>A <gi>peRef</gi> indicates that a parameter entity reference should
occur at this point in the DTD. The <gi>peRef</gi> is empty; its
<att>n</att> attribute gives the name of the entity. For now, no check
is made that the parameter entity is declared anywhere, so that
references to external files may be included in DTD fragments without
<gi>entDoc</gi> crystals having to be built for them. [The wisdom of
this decision is open for discussion.]
<p>Need example.
<p>A <gi>dtdRef</gi> element indicates that the content of some other
<gi>dtdFrag</gi> element should be inserted here; the <att>dtdFrag</att>
attribute gives its <att>ID</att>. OddP2X fetches the section number
and name of the other <gi>dtdFrag</gi> (the latter given as the value of
its <att>N</att> attribute) and prints it as a comment, in the form:
<eg>
<![ CDATA [
<!-- ... declarations from section n.n (title of fragment)
go here ... -->
]]>
</eg>
OddDtd bodily inserts a similar comment, but then follows it with the
contents of the specified DTD fragment, and marks its end with a comment
saying that the embedded DTD fragment is now ended. OddRef ignores
<gi>dtdFrag</gi>s entirely.
<p>Other comments may be specified using the <gi>commDecl</gi> element.
These should all be block prose comments --- no indented lists or other
fancy formatting ---, as they may be reformatted as paragraphs by OddP2X
and OddDtd.
<p>Need example.
<div3><head>Processing of DTD Fragments</head>
<p>OddP2X processes a <gi>dtdFrag</gi> by printing a nice header for the
fragment and then nicely printing its contents: the comment, element
and attribute list declarations are printed with appropriate delimiters,
and each <gi>dtdRef</gi> element present generates a comment with a
cross-reference to the appropriate DTD fragment.
<p>OddDtd processes a <gi>dtdFrag</gi> by emitting a comment identifying
the fragment, then writing out the contents of the fragment. Comment,
element, and attList declarations are written out with appropriate
delimiters, <gi>dtdRef</gi> cross-references are handled by recursively
processing the appropriate <gi>dtdFrag</gi>. Finally, an ending comment
is emitted. The file into which all this is written is given by the
<gi>dtdFrag</gi> <att>file</att> attribute.
<p>If the dtdFrag element bears a <att>contin</att> attribute, it should be
viewed as a continuation of the <gi>dtdFrag</gi> whose ID is given as
the <att>contin</att> value, and printed / copied immediately after it.
A series of such continuations will be printed / copied in order. It is
a semantic error for the ID in question to belong to anything other than
a <gi>dtdFrag</gi>.
<p>Examples needed here.
<p>The <gi>dtdFrag</gi> element and its constituent parts are defined by
the following declarations:
<eg id=oadd2>
<![ CDATA [
<!-- 3.1.4: DTD Fragments -->
<!ELEMENT dtdFrag - O (tagDecl | dtdRef | commDecl |
entDecl | claDecl | peRef)* >
<!ATTLIST dtdFrag %a.global;
file NAME tei.dtd
contin IDREF #IMPLIED >
<!ELEMENT tagDecl - - EMPTY >
<!ATTLIST tagDecl %a.global;
tagDoc IDREF #REQUIRED >
<!ELEMENT dtdRef - O EMPTY >
<!ATTLIST dtdRef %a.global;
target CDATA #REQUIRED >
<!ELEMENT commDecl - - (#PCDATA) >
<!ATTLIST commDecl %a.global; >
<!ELEMENT entDecl - O EMPTY >
<!ATTLIST entDecl %a.global;
entDoc IDREF #REQUIRED >
<!ELEMENT claDecl - - EMPTY >
<!ATTLIST claDecl %a.global;
classDoc IDREF #REQUIRED
type (model | atts) #REQUIRED >
<!ELEMENT peRef - O EMPTY >
<!ATTLIST peRef %a.global; >
]]>
</eg>
<!-- reference crystals for: -->
<!-- dtdFrag tagDecl dtdRef commDecl entDecl claDecl peRef -->
<!-- OddAdd2.ref: reference crystals for tags in oddadd.dtd: -->
<!-- dtdFrag tagDecl dtdRef commDecl entDecl claDecl peRef -->
<!-- This file is part of Odd.odd. -->
<!-- Revisions: -->
<!-- 27 Mar 92 : CMSMcQ : normalize case of identifiers -->
<!-- 18 Mar 92 : CMSMcQ : more changes, claDecl not pedecl -->
<!-- 8 Mar 92 : CMSMcQ : some changes -->
<!-- 8 Jan 92 : CMSMcQ : made file separate -->
<!-- ************************************************ dtdFrag -->
<!-- ************************************************** tagDecl -->
<!-- dtdRef: -->
<!-- ************************************************* dtdRef -->
<!-- *********************************************** commDecl -->
<!-- ************************************************ entDecl -->
<!-- ************************************************* claDecl -->
<!-- ************************************************** peRef -->
<!-- no added elements for P2X specifically, except perhaps a
specialized version of tagList as a glossary list. -->
<!>
<div2 n=2><head>Tags for Reference Material</head>
<p>In addition to the running prose documentation of the tag set, the
Odd system produces reference material describing each tag and
attribute. Some of the information needed for the reference section is
provided in the Odd input files within <gi>tagDoc</gi>,
<gi>classDoc</gi>, and <gi>entDoc</gi> elements (called here
<cited>reference crystals</cited>); other pieces of information used in
the reference section are generated from <gi>dtdFrag</gi>s and the like.
In addition to providing much of the reference matter, the reference
crystals are also used to generate the prose descriptions of tags in tag
lists and the SGML declarations in DTD fragments and DTD files.
<div3 id=o.tagDoc><head>tagDoc: Tag Documentation Crystal</head>
<p>The <gi>tagDoc</gi> crystal documents one SGML element, providing
its generic identifier, full name, definition, examples, and
the like. The attributes of the element are documented with an embedded
<gi>attList</gi> crystal (documented below).
<p>The tags used in the Odd <gi>tagDoc</gi> crystal are these:
<list type=gloss>
<label><gi>tagDoc</gi></label>
<item>contains reference information concerning one SGML element type</item>
</list>
<p>In addition to those used in Odd <gi>tagDoc</gi>s, P2X
<gi>tagDoc</gi>s use the following tags:
<list type=gloss>
</list>
<p>As an example of a complete tag documentation crystal, consider the
<gi>tagDoc</gi> for the <gi>gi</gi> element described above:
<eg>
<![ CDATA [
<tagDoc id=gi usage=rec>
<gi>gi
<name>generic identifier
<desc>marks a generic identifier for an SGML element type.
<attList>
</attList>
<exemplum><eg><![ CDATA [
The <gi>entry</gi> element contains an entire dictionary entry.
]<!>]></eg>
<remarks><p>Although it may be printed in angle brackets, distinguish
<gi>gi</gi> from <gi>tag</gi>: the latter is for complete start- or
end-tags, the former for isolated generic identifiers.
<part type=top name=ext>
<classes names='teiTerm'>
<dataDesc>Should be a valid SGML name.
<elemDecl>- O (#PCDATA)
</elemDecl>
<xref type=div3 target=od.names>
</tagDoc>
]]>
</eg>
<p>The tags for tag documentation and other crystals are defined in
three distinct files: OddRef.dtd for those used only in Odd documents,
P2xRef.dtd for those unique to P2X documents, and ComRef.dtd for those
with the same definition in both document types. The relevant portion
of OddRef.dtd is this:
<eg id=oreftd>
<![ CDATA [
<!-- 3.2.1: Reference Crystals for Odds -->
]]>
</eg>
<p>The corresponding definitions in P2xRef.dtd are these:
<eg id=preftd>
<![ CDATA [
<!-- 3.2.1: Reference Crystals for P2X Documents -->
]]>
</eg>
<p>The definitions for <gi>tagDoc</gi> components in ComRef.dtd
are these:
<eg id=creftd>
<![ CDATA [
<!-- 3.2.1: Common Reference Crystal Elements -->
]]>
</eg>
<!-- now add the reference crystals for this section -->
<!-- OddRefT: reference crystals for OddRef tagDocs -->
<!-- Revisions: -->
<!-- 27 Mar 92 : CMSMcQ : normalize case in identifiers -->
<!-- 19 Mar 92 : CMSMcQ : level tagDoc to tagDoc -->
<!-- 18 Mar 92 : CMSMcQ : made file -->
<!-- ************************************************* tagDoc -->
<!-- *************************************************** name -->
<!-- *************************************************** desc -->
<!-- *********************************************** exemplum -->
<div3 id=o.cladoc><head>classDoc: Element Class Documentation Crystal</head>
<p>The <gi>classDoc</gi> crystal documents a class of elements.
The membership of the class is not given within the crystal; it is
governed instead by the <gi>classes</gi> element in the <gi>tagDoc</gi>
and <gi>classDoc</gi> crystals describing the members and subclasses of
the class. This means that when new tags are added to a tag set, they
can be assigned to classes without having to change the class
documentation.
<p>The tags used in class documentation crystals include:
<list type=gloss>
<label><gi>classDoc</gi></label>
<item>contains reference information for one element class: either
elements which appear together in SGML content models, or elements which
share some common attributes.</item>
</list>
<p>[Examples here.]
<p>Like those of the preceding section. the SGML declarations for
these elements are found in three distinct files: apart from those
already defined, the file <term>OddRef.dtd</term> contains:
<eg id=orefcd>
<![ CDATA [
<!-- 3.2.2: Odd classDoc Crystals -->
]]>
</eg>
<p>The file <term>P2xRef.dtd</term> contains:
<eg id=prefcd>
<![ CDATA [
<!-- 3.2.2: P2X Reference Crystals for Classes -->
]]>
</eg>
<p>The file <term>ComRef.dtd</term> contains:
<eg id=crefcd>
<![ CDATA [
<!-- 3.2.2: Common Reference Crystals for Classes -->
]]>
</eg>
<!-- now add the reference crystals for this section -->
<!-- OddRefC: reference crystals for OddRef classDocs -->
<!-- Revisions: -->
<!-- 27 Mar 92 : CMSMcQ : normalize case -->
<!-- 19 Mar 92 : CMSMcQ : made file -->
<!-- *********************************************** classDoc -->
<div3 id=o.entDoc><head>entDoc: Entity Documentation Crystal</head>
<p>The <gi>entDoc</gi> crystal documents a general entity or parameter
entity.
<p>The tags used in entity documentation crystals include:
<list type=gloss>
<label><gi>entDoc</gi></label>
<item>contains reference information about one entity</item>
</list>
<p>[Examples here.]
<p>Like those of the preceding sections, the SGML declarations for
these elements are found in three distinct files: apart from those
already defined, the file <term>OddRef.dtd</term> contains:
<eg id=orefed>
<![ CDATA [
<!-- 3.2.3: Odd Reference Crystals for Entities -->
]]>
</eg>
<p>The file <term>P2xRef.dtd</term> contains:
<eg id=prefed>
<![ CDATA [
<!-- 3.2.3: P2X Reference Crystals for Entities -->
]]>
</eg>
<p>The file <term>ComRef.dtd</term> contains:
<eg id=crefed>
<![ CDATA [
<!-- 3.2.3: Common Reference Crystals for Entities -->
]]>
</eg>
<!-- now add the reference crystals for this section -->
<!-- OddRefE.odd: reference crystals for Odd entDocs etc. -->
<!-- Revisions: -->
<!-- 27 Mar 92 : CMSMcQ : normalize case -->
<!-- 22 Mar 92 : CMSMcQ : correct elemDecl (kill trailing >) -->
<!-- 19 Mar 92 : CMSMcQ : made file -->
<div3 id=o.atts><head>attList: Attribute Documentation</head>
<p>Attributes may be defined either for individual elements, in which
case they are documented in the relevant <gi>tagDoc</gi> crystal, or for
classes of elements, in which case they are documented in the relevant
<gi>classDoc</gi>. In either case, an <gi>attList</gi> crystal is used,
containing one <gi>attDef</gi> crystal for each attribute.
<p>Information about the attributes is printed as part of tag lists,
when the attribute names are included in the <att>atts</att> attribute
of a <gi>tagDesc</gi> element, or in separate lists for attributes
assigned to whole classes of elements, when their names are included in
the <att>atts</att> value of an <gi>adList</gi> element. The
documentation crystals are also used to generate attribute list
declarations for elements.
<p>The tags used to document attributes are:
<list type=gloss>
<label><gi>attList</gi></label>
<item>groups attribute definitions in a tag or class documentation
crystal</item>
<label><gi>attDef</gi></label>
<item>contains documentation for one attribute for one element or
element class</item>
</list>
<p>[Examples here.]
<p>All tags used for attribute lists are common to both Odd and P2X
documents; their definitions occur in file <term>ComRef.dtd</term>.
<eg id=crefad>
<![ CDATA [
<!-- 3.2.4: Common Reference Crystals for Attributes -->
]]>
</eg>
<!-- now add the reference crystals for this section -->
<!-- OddRefA.odd: reference crystals for attLists in Odds. -->
<!-- Revisions: -->
<!-- 27 Mar 92 : CMSMcQ : normalize case -->
<!-- 19 Mar 92 : CMSMcQ : made file -->
<!-- ************************************************ attList -->
<!-- ************************************************* attDef -->
<!>
<div1 n=4><head>DTDs and DTD Fragments</head>
<p>The DTDs for the Odd system are broken up into several files, which
are described in this section.
<div2 id=s3.1><head>Overview of DTDs and DTD Fragments</head>
<p>Each type of file has its own DTD; some are constructed from several
parts. The various DTD types and the fragments from which they are made
are:
<list type=gloss>
<label>Odd.dtd <item>The DTD for the working files from which P2 will be
generated. It is added to Tiny.dtd (for the prose base), and includes
OddRef.dtd (for the embedded tagDoc elements), and OddAdd.dtd (for
additional elements needed in the Odd). It also provides modified
definitions for various element classes, so as to include the added
elements in <term>%soup;</term>. (It also redefines <term>p.float</term>,
<term>f.edit</term>, and <term>f.misc</term> to omit tags and keep the
definition of <term>soup</term> within limits acceptable to the default
capacities of SGML processors.)
<!>
<label>P2x.dtd <item>The DTD for the (distributable) form of TEI P2; an
extension of what is documented in TEI P2 itself. During drafting, we
will use a working DTD which is added to Tiny.dtd (for the prose base)
and includes P2xRef.dtd (for the reference list of tags and attributes)
and P2xAdd.dtd (for any additional elements needed in the prose or
elsewhere). Like Odd.dtd, P2x.dtd redefines some element classes.
<!>
<label>Ref.dtd <item>The DTD for the tagDoc, attDoc, and other elements
to be included in the reference list of TEI P2. This is mostly just a
reference to P2xRef.dtd and ComAdd.dtd (for definitions of <gi>gi</gi>
etc.), but during drafting might also include its own front matter etc.
so we can print reference materials in separate working documents. Like
the other top-level DTDs, Ref.dtd redefines some element classes; in
order for <term>soup</term> to work correctly, it also includes the
low-level elements from Tiny.dtd (but not the basic structure).
<!>
<label>Tiny.dtd <item>based on Toy2.dtd---this will be replaced in final
form of TEI P2 by TEI2.dtd itself, and in TEI P3 by TEI.dtd itself.
This will define a prose base with no special additions or extensions
for tag set documentation or development. In its current incarnation,
Tiny.dtd includes TinyEnts.dtd and TinySoup.dtd as separate files for
the definition of element classes and low-level elements; Tiny.dtd
itself defines the structural base for prose.
<!>
<label>TinyEnts.dtd <item>DTD fragment containing definitions for
parameter entities of element classes; also the definition of global
attributes. This is separate from Tiny.dtd so that it can be embedded
separately by users (as is done by Odd.dtd, P2x.dtd, and Ref.dtd).
<!>
<label>TinySoup.dtd <item>DTD fragment containing definitions for
low-level elements (soup, broth, etc.). This is separate from Tiny.dtd
so that Ref.dtd, which needs low-level elements but not structural
elements, can embed this file separately.
<!>
<label>P2XRef.dtd <item>DTD fragment containing definitions for tagDoc
etc. as they should be produced by the OddRef processor. It differs
from OddRef.dtd in adding elements like <gi>parents</gi> and
<gi>children</gi> to the <gi>tagDoc</gi> crystal.
<!>
<label>OddRef.dtd <item>DTD fragment containing definitions for tagDoc
etc. as they should be allowed in the Odd document. It differs from
P2xRef.dtd in omitting elements like <gi>parents</gi> and
<gi>children</gi> (which are to be generated by the OddRef processor)
and may make other elements optional instead of required.
<!>
<label>ComRef.dtd <item>tags defined identically by OddRef.dtd and
P2xRef.dtd.
<!>
<label>P2xAdd.dtd <item>miscellaneous additions to Tiny.dtd needed for
P2X documents: <gi>tag</gi>, <gi>att</gi>, <gi>gi</gi>, etc. (Possibly
should contain <gi>tagList</gi>, <gi>dtdFrag</gi>, etc. as well, though
these are not generated at present by the OddP2X processor.) It differs
from OddAdd.dtd in that it is designed for the output (not the input) of
the OddP2X processor.
<!>
<label>OddAdd.dtd <item>miscellaneous additions to Tiny.dtd needed for
Odd documents: <gi>tag</gi>, <gi>att</gi>, <gi>gi</gi>,
<gi>tagList</gi>, <gi>dtdFrag</gi>, etc. It differs from P2XAdd.dtd in
that it is designed for the input (not the output) of the OddP2X
processor.
<!>
<label>ComAdd.dtd <item>tags defined identically by OddAdd.dtd and
P2xAdd.dtd.
</list>
<div2 id=s3.2><head>The Odd Tags and DTD</head>
<p>As noted above, the Odd DTD is split among several files for clarity of
construction and ease of maintenance. The specifics of the DTD are
described in this section.
<div3 id=s3.2.1>
<head>Odd.dtd: Redefinitions of Element Classes</head>
<p>The file Odd.dtd itself serves mostly as a driver file to include the
component parts of the DTD. Because Odd.dtd is invoked in the DTD
subset, it need not itself invoke the prose base tag set (Tiny.dtd).
Instead, it first defines some parameter entities which will be used in
the prose base, allowing the Odd tags to appear within the prose base:
<eg id=oddbase>
<![ CDATA [
<!-- 4.2.1: Odd.dtd: tags for defining tag sets -->
<!-- Draft 1, CMSMcQ, 25 November 1991 (from DTDweb.dtd) -->
<!-- This file defines elements needed for Odd documents not -->
<!-- included in Tiny.dtd (the prose base). -->
<!-- Revisions: -->
<!-- 12 Dec 91 : MSM : copy mod to LIST, ITEM from P2X.dtd. -->
<!-- 6 Dec 91 : MSM : change names for external entities. -->
<!-- 26 Nov 91 : MSM : redefine f.misc, p.float, f.edit to -->
<!-- get under the 240-character, 32-token limits -->
<!-- 25 Nov 91 : MSM : made file -->
<!-- N.B. this file is designed to be embedded in a DTD -->
<!-- subset when the system DTD called is Tiny.dtd. It may -->
<!-- need to be revised when tei2.dtd is used instead. -->
<!-- 1 Glue to add the additional elements to base. With -->
<!-- these, our new tags can appear in broth and soup. -->
<!ENTITY % x.float'' >
<!ENTITY % m.float'%x.float ' >
<!ENTITY % x.edit'' >
<!ENTITY % m.edit'%x.edit ' >
<!ENTITY % x.misc'' >
<!ENTITY % m.misc'%x.misc ' >
<!ENTITY % x.list 'tagList | adList |' >
<!ENTITY % x.crys 'dtdFrag | tagDoc | entDoc | classDoc | eg |' >
]]>
</eg>
Then it embeds the prose base's own parameter entity declarations
(tinyents.dtd), so they can be used in the element declarations for Odd
tags, and overrides the default declarations of two elements (list and
item).
<eg id=oddbase2>
<![ CDATA [
<!-- 4.2.1: Odd.dtd: tags for defining tag sets (cont'd) -->
<!-- (continuation of sec. 4.2.1) -->
<!-- Now define global classes etc., and suppress later redef -->
<!ENTITY % xents system 'tinyents.dtd' >
%xents;
<!ENTITY % tinents '' >
<!-- 1c Now define any local modifications to standard defs. -->
<!-- Redefine list so its TYPE attribute can accept GLOSS -->
<!-- val. Also redefine content model to allow head for -->
<!-- labels if and only if labels are actually used in the -->
<!-- list. -->
<!ENTITY % list 'IGNORE' >
<!ELEMENT list - - (head?, ( (item*) | (head.lab?,
head.it?, (label, item)+))) >
<!ATTLIST list %a.global;
type (ordered | bullets | noorder | simple | gloss)
simple >
<!-- redefine list items so they can include lists even if -->
<!-- the item is not a paragraph sequence. -->
<!ENTITY % item 'IGNORE' >
<!ELEMENT item - O (%p.seq; | (list | %broth;)*) >
<!ATTLIST item %a.global; >
]]>
</eg>
Finally it embeds references to the two files OddRef.dtd and oddadd.dtd,
which actually define the elements and their attributes.
<eg id=oddbase3>
<![ CDATA [
<!-- 4.2.1: Odd.dtd: tags for defining tag sets (cont'd) -->
<!-- (continuation of sec. 4.2.1) -->
<!-- 2 Elements for documenting tags, to make alpha list with -->
<!ENTITY % oddref system 'oddref.dtd' >
%oddref;
<!-- 3 Special elements for embedding in prose, for tag lists -->
<!ENTITY % oddadd system 'oddadd.dtd' >
%oddadd;
]]>
</eg>
<!-- embed ref crystals needed here -->
<!-- OddMisc.Odd: reference crystals for Odd.dtd -->
<!-- This file documents classes, entities, and tags -->
<!-- used in the file odd.odd: -->
<!-- classes float, edit, misc. -->
<!-- entities x.list, x.crys, xents, xdummy, -->
<!-- cs.list, cs.item, f.oddref, f.oddadd -->
<!-- tags list, item -->
<!-- Revisions: -->
<!-- 27 Mar 92 : CMSMcQ : normalize case of identifiers -->
<!-- 22 Mar 92 : CMSMcQ : correct class memberships -->
<!-- 19 Mar 92 : CMSMcQ : add more crystals -->
<!-- 18 Mar 92 : CMSMcQ : separated from Odd.Odd. -->
<!--**************************************************** item -->
<!--**************************************************** list -->
<!-- ********************************************* edit class -->
<!-- ********************************************* misc class -->
<!-- ******************************************** float class -->
<!-- ******************************************** list entity -->
<!-- ******************************************** crys entity -->
<!-- ******************************************* xents entity -->
<!-- ***************************************** tinents entity -->
<!-- ***************************************** cs.list entity -->
<!-- ***************************************** cs.item entity -->
<!-- **************************************** f.oddref entity -->
<!-- **************************************** f.oddadd entity -->
<div3 id=s3.2.2><head>OddAdd.dtd: Additional Tags for Prose</head>
<div3 id=s3.2.3><head>OddRef.dtd: Tag Documentation Crystals</head>
<div2 id=s3.3><head>The P2X DTD</head>
<!>
<div1 id=s3 n=5><head>Processors</head>
<p>Four processors are envisaged as part of this system. Detailed
specifications of their behavior is given in the appropriate LTD
(link-type definition) files. (The LTD files are now out of date; they
assume an earlier version of the Odd tag set and have not been
replaced.)
<list>
<label>DtdOdd <item>reads a DTD and generates partial tagDoc crystals
suitable for inclusion into an Odd file.
<label>OddDtD <item>reads an Odd file and generates the corresponding
DTD fragment(s).
<label>OddRef <item>reads an Odd file and generates files containing the
corresponding tagDoc, attDoc, and other crystals, suitable for inclusion
in a reference list.
<label>OddP2X <item>reads an Odd file and generates files containing
prose documentation of the tag set suitable for printing directly; this
involves expanding the <gi>tagList</gi>s and <gi>dtdFrag</gi>s of the
Odd file into material which does not require cross reference among
elements. It is the OddP2X output which will be processed by formatting
software to print TEI P2.
</list>
<!>
</body>
<back>
<div1><head>Summary of Tiny.dtd Tags</head>
<p>The following tags of Tiny.dtd are used in Odd and P2X files. For
details, see the corresponding tags in TEI P1 and consult files Tiny.dtd
and TinySoup.dtd (or check to see whether an Odd file for these DTDs has
been prepared).
<list type=gloss>
<label><gi>anchor</gi> <item>empty tag to mark a location
<label><gi>author</gi> <item>in a bibliographic citation, marks
author of work cited
<label><gi>back</gi> <item>back matter
<label><gi>body</gi> <item>body of text
<label><gi>cb</gi> <item>column-break (empty)
<label><gi>cit.ref</gi> <item>reference to a citation
<label><gi>cit.str</gi> <item>structured citation
<label><gi>citation</gi> <item>bibliographic citation
<label><gi>cited</gi> <item>word named not used
<label><gi>city</gi> <item>in citation, city of publication
<label><gi>comment</gi> <item>in citation, comment on work cite
<label><gi>corpus</gi> <item>top-level tag surrounding a
group of TEI.1 documents (not expected to be used in P2)
<label><gi>detail</gi> <item>in citation, miscellaneous
publication details
<label><gi>div0</gi> <item>outer-level text division (optional);
in P2, this is a used to tag parts
<label><gi>div1</gi> <item>main division (in P2, chapters)
<label><gi>div2</gi> <item>text division (in P2, sections)
<label><gi>div3</gi> <item>text division (in P2, sections)
<label><gi>div4</gi> <item>text division (in P2, sections)
<label><gi>editor</gi> <item>in citation, name of editor of work
cited
<label><gi>emph</gi> <item>emphatic/stressed word or phrase
<label><gi>encDecl</gi> <item>in header, encoding declaration
<label><gi>epigraph</gi> <item>quotation at head of text or section
<label><gi>filDescr</gi> <item>in header, file description
<label><gi>foreign</gi> <item>foreign word
<label><gi>front</gi> <item>front matter
<label><gi>gloss</gi> <item>definition or translation equivalent
of a word, typically a foreign word or technical term
<label><gi>head.it</gi> <item>head of the item column in a glossary
list
<label><gi>head.lab</gi> <item>head of the label column in a
glossary list
<label><gi>head</gi> <item>head/title of div or list
<label><gi>header</gi> <item>required documentation of electronic
text
<label><gi>hilited</gi> <item>miscellaneous text marked by font
shift or other, for unspecified reasons (in P2, deprecated except in
examples of typography)
<label><gi>imprint</gi> <item>in citation, information about
publication
<label><gi>include</gi> <item>include external entity (abortive
attempt to provide hook for external entities; possibly usable for NDATA
or SUBDOC entities, but probably pointless)
<label><gi>indexed</gi> <item>marker for index entries in running
text
<label><gi>item</gi> <item>in a list, one of the things being
listed
<label><gi>label</gi> <item>in a list, the label for an item:
possibly the number or other enumerator; in a glossary list, the term
defined in the item
<label><gi>lb</gi> <item>line break
<label><gi>list.cit</gi> <item>list of citations
<label><gi>list</gi> <item>list
<label><gi>mileSton</gi> <item>milestone
<label><gi>note</gi> <item>footnote, marginal note, endnote, or
intext block note
<label><gi>ornament</gi> <item>printer's ornament
<label><gi>p</gi> <item>paragraph
<label><gi>pb</gi> <item>page break
<label><gi>publ</gi> <item>in a citation, publication
information
<label><gi>q.mark</gi> <item>phrase enclosed in quotation marks
for unspecified reason (in P2, deprecated except in typographic
examples)
<label><gi>q</gi> <item>quotation, direct discourse
<label><gi>resp</gi> <item>in citation, statement of
responsibility (e.g. <q>illustrations by Maurice Sendak</q>)
<label><gi>revHist</gi> <item>in header, revision history
<label><gi>rule</gi> <item>printer's (vertical or horizontal)
rule
<label><gi>s</gi> <item>arbitrary segment of any type
<label><gi>series</gi> <item>in citation, series information
<label><gi>sic</gi> <item>marks editorial suspicion of a phrase
(not expected to be used in P2)
<label><gi>soCalled</gi> <item>phrase enclosed in <soCalled>scare
quotes</soCalled> or <soCalled>inverted commas</soCalled> as a
distancing device
<label><gi>source</gi> <item>in header's file description,
bibliographic description of copy text (includes <gi>citation</gi>
element)
<label><gi>TEI.1</gi> <item>top-level TEI document tag, contains
header and text
<label><gi>term</gi> <item>technical term
<label><gi>text</gi> <item>main part of TEI document, contains
front, body, back
<label><gi>title.p</gi> <item>title of an article, poem, chapter,
or other item published as part of a monograph, journal, or collection
<label><gi>title</gi> <item>in citation or running prose, title
of a published work (monograph or journal)
<label><gi>tp.auth</gi> <item>author of a document, as given on
title page
<label><gi>tp.date</gi> <item>date of document
as given on title page
<label><gi>tp.part</gi> <item>miscellaneous phrase on title page
<label><gi>tp.publ</gi> <item>publication information for a
document
as given on title page
<label><gi>tp.title</gi> <item>title of document
as given on title page
<label><gi>tPage</gi> <item>title page (within front matter)
<label><gi>trailer</gi> <item>trailing statement or piece at end of
chapter or book (e.g. <q>End of Part I</q>)
<label><gi>vertical</gi> <item>vertical space
<label><gi>xref</gi> <item>cross reference
</list>
<p>The following tags in Tiny.dtd are <emph>not</emph> available in Odd
or P2X documents:
<list type=gloss>
<label><gi>abbrev</gi> <item>abbreviation
<label><gi>add</gi> <item>material added by an editor
<label><gi>corr</gi> <item>material corrected by an editor
<label><gi>date</gi> <item>calendar date
<label><gi>dates</gi> <item>date range
<label><gi>del</gi> <item>material deleted by an editor
<label><gi>norm</gi> <item>material normalized by an editor
<label><gi>num</gi> <item>number/numeral
<label><gi>propName</gi> <item>proper noun
<label><gi>salute</gi> <item>salutation in a letter
<label><gi>signed</gi> <item>signature (in a letter or preface)
</list>
<div1><head>Summary of Tags Common to Odd and P2X DTDs</head>
<list type=gloss>
<label><gi>att</gi> <item>attribute name
<label><gi>attDef</gi> <item>attribute definition crystal
<label><gi>attList</gi> <item>list of attDef crystals
<label><gi>attName</gi> <item>full linguistic form of attribute name
<label><gi>class</gi> <item>name of element class
<label><gi>classDoc</gi> <item>element class documentation crystal
<label><gi>classes</gi> <item>indicates which classes a tag
or class belongs to (empty in Odd)
<label><gi>dataDesc</gi> <item>prose description of legal content of
an element
<label><gi>dataType</gi> <item>standard-form definition of attribute
value type
<label><gi>default</gi> <item>attribute default specification
<label><gi>desc</gi> <item>short prose description of an
element, attribute, entity, or class
<label><gi>eg</gi> <item>example
<label><gi>elemDecl</gi> <item>formal declaration of element
(omissibility, content model, exceptions -- no gi)
<label><gi>entDoc</gi> <item>entity documentation crystal
<label><gi>entname</gi> <item>name of entity
<label><gi>equiv</gi> <item>similar or equivalent tags or
constructs in other markup languages
<label><gi>exemplum</gi> <item>example surrounded by optional
paragraphs of prose commentary
<label><gi>gi</gi> <item>generic identifier (tag name)
<label><gi>item</gi> <item>basic element of a list
<label><gi>list</gi> <item>sequence of items
<label><gi>name</gi> <item>full linguistic form of gi, attribute
name, or other abbreviated form
<label><gi>part</gi> <item>indicates which part of the tag set
an element belongs to (empty in Odd, character data in P2X)
<label><gi>remarks</gi> <item>sequence of paragraphs with free-form
commentary on usage or other peculiarities of a construct
<label><gi>string</gi> <item>entity text of an entity (in
<gi>entDoc</gi>)
<label><gi>tag</gi> <item>SGML tag given in running text as an
example
<label><gi>tagDoc</gi> <item>element documentation crystal
<label><gi>val</gi> <item>specific value for an attribute
<label><gi>valDesc</gi> <item>prose description of what an
attribute's value should be and mean
<label><gi>valList</gi> <item>list of <gi>val</gi>, <gi>desc</gi>
pairs giving legal, recommended, or sample values for an attribute
</list>
<div1><head>Summary of Tags Unique to Odds</head>
<list type=gloss>
<label><gi>adList</gi> <item>in prose, empty tag indicating need
for a glossary list of attributes associated with an element class
<label><gi>claDecl</gi> <item>in DTD fragment, indicates
location of a parameter entity declaration for an element class
<label><gi>commDecl</gi> <item>comment in DTD fragment, to be
written as part of DTD file
<label><gi>dtdFrag</gi> <item>structured fragment of a DTD
<label><gi>dtdRef</gi> <item>indicates location at which another
DTD fragment is to be embedded
<label><gi>entDecl</gi> <item>in DTD fragment, indicates location
for an entity declaration
<label><gi>peRef</gi> <item>in DTD fragment, indicates location
for a parameter-entity reference.
<label><gi>tagDecl</gi> <item>in DTD fragment, indicates location
of an element- and attList-declaration pair
<label><gi>tagDesc</gi> <item>in tag list, indicates tag to be
described and attributes to be listed for it
<label><gi>tagList</gi> <item>sequence of tag names and
descriptions, with embedded lists of attributes and values
</list>
<div1><head>Summary of Tags Unique to P2X</head>
<list type=gloss>
<label><gi>attDoc</gi> <item>attribute documentation crystal
<label><gi>attlDecl</gi> <item>formal attribute list declaration for
an element
<label><gi>children</gi> <item>list of elements which can appear as
immediate constituents of an element
<label><gi>files</gi> <item>list of files in which an element is
declared
<label><gi>members</gi> <item>list of members of an element class
<label><gi>parents</gi> <item>list of elements within which an
element may appear as an immediate constituent
<label><gi>refBy</gi> <item>in entity documenation crystal, list
of entities which refer to an entity
</list>
</back>
</text>
</TEI1>
Prepared by Robin Cover for The XML Cover Pages archive. See the TEI website.
