[Cache HTML (display text) from http://www.tei-c.org/Vault/ED/edw29.sgm; please use this canonical URL/source if possible.]
TEI EDW30 ODD
Simple Example of ODD Text
Lou Burnard and C.M. Sperberg-McQueen
5 June 1992
<!-- As requested, there follows a VERY SIMPLE demonstration of the -->
<!-- way in which ODD documents are created for incorporation into -->
<!-- P2. If you can produce documents tagged like this one, our task -->
<!-- will be greatly reduced. If you cannot, you can still help greatly -->
<!-- by not introducing other tags or conventions than those described -->
<!-- here. If you want to introduce comments (for the editors eyes only) -->
<!-- into the text they should be marked off by SGML comment -->
<!-- flags like those surrounding this passage and the annotations in -->
<!-- what follows. -->
<!-- Don't despair if this all looks very forbidding! A plain ASCII text -->
<!-- entirely devoid of tags will not be rejected out of hand! But -->
<!-- several people did request more guidance on how drafts could -->
<!-- be made as useful as possible to your hard-pressed editors... -->
<div2 id=p2.231><head>Paragraphs</head>
<!-- In P2, each PART is a DIV0, each CHAPTER a DIV1, and each SECTION -->
<!-- a DIV2. The ID attribute specifies a canonical reference, -->
<!-- prefixed by the string 'P2.': this section is therefore part 2, -->
<!-- chapter 3, section 1. -->
<!-- The HEAD element contains the title of the section. It is nice, -->
<!-- but not essential, for it to be on the same line as the DIV1 tag. -->
<p>As the smallest regular unit of prose, the paragraph represents the
fundamental formal organizational unit for all prose text. Since prose
can appear not only in the base tag set for prose
(section <xref type=div1 target=p2.31>),
<!-- This is a cross-reference. If, as is probably the case, you don't know -->
<!-- the ID value for the section to which you want to refer, use the -->
<!-- section number given in the outline of contents for P2, and add a -->
<!-- description within a comment to identify it more precisely. -->
but also in all other base tag sets, sometimes
in large units and sometimes in small, paragraphs and their contents may
occur in all other base tag sets as well.
<p>Paragraphs can contain virtually any of the other elements described
<!-- Note that the P tag does not require a corresponding end tag -->
within this chapter, as well as many other elements specific to
individual base or additional tag sets. These include:
<list type=bullets>
<item>phrase-level elements like emphasis, quotation, or font shift
<item>floating structural units (<term>crystals</term>) such as
bibliographic references or notes
<item>analytic or interpretive tags like those marking names,
abbreviations, etc.
<item>items specific to individually activated additional tag sets like
those for cross references, formulae, analysis and interpretation, or
text criticism
</list>
<!-- The LIST tag generates a formatted list, with bulletted items if the -->
<!-- TYPE=BULLETS, or numbers if it is ORDERED. For glossary lists, -->
<!-- use TYPE=GLOSS and supply LABEL elements as well as ITEMs within it -->
<!-- (see later). Note that the TYPE attribute must be supplied. -->
<p>In all cases, paragraphs are tagged with the <gi>p</gi> tag, which
<!-- When you have occasion to refer to a TEI defined element by name, -->
<!-- enclose the name within the GI tag as in this example. If you want to -->
<!-- refer to the TAG itself (as opposed to the whole element) use the TAG -->
<!-- tag as in the next paragraph -->
has the following description:
<tagList>
<tagDesc tagDoc=p>
</tagList>
<!-- The above TAGLIST will generate a glossary list containing -->
<!-- names and descriptions for the element specified by the TAGDOC -->
<!-- attribute on each TAGDESC element within it (only one in this case). -->
<!-- It will also generate descriptions for any attributes specified on -->
<!-- an ATTS attribute, which in this case we have not got. -->
<!-- The required information is taken from a TAGDOC element, which must -->
<!-- be supplied somewhere else in the current document (see below) -->
<!-- First however, here's how examples in the running text must be -->
<!-- marked up so that the various processors do not go berserk... -->
<eg>
<![ CDATA [
<body>
<p>Gen. Sheridan says <q>If the thing is pressed I think that Lee will
surrender.</q> Let the <emph>thing</emph> be pressed.</p>
</body>
]]>
</eg>
<!-- Lincoln to Grant, 7 Apr 1865, v. 2 p. 696. -->
<!-- Note the inclusion of the source for the quotation, -->
<!-- enclosed in the comment above -->
<!-- A cited example is one of the few places where spaces and newlines -->
<!-- really count in the draft. The two magic lines before the start of -->
<!-- the example above, and the two lines at its end *must* be given as -->
<!-- above. Spaces and newlines within the example will be preserved in -->
<!-- the output, so you should make the lines short -->
<p>The formal declaration of the <gi>p</gi> tag is this:
<dtdFrag id=d2231 n='Paragraph'>
<tagDecl tagDoc=p>
</dtdFrag>
<!-- At the end of each section, insert a DTD fragment as above for the -->
<!-- elements defined in that section. The DTDfrag must have an ID (we -->
<!-- have adopted the convention of naming them after the IDs of the -->
<!-- section in which they occur, but this is not crucial) and should have -->
<!-- a self-explanatory N attribute. It contains a TAGDECL element for -->
<!-- each element for which an element declaration is required. The -->
<!-- element concerned is named by the TAGDOC attribute, in the same -->
<!-- way as the TAGDESCs in a TAGLIST. -->
<!-- That's the end of the text part of this description. There now -->
<!-- follows the text of the TAGDOC crystal itself. There must be one -->
<!-- and only one such crystal for each element described. We have found -->
<!-- it convenient to keep the crystals separate from the text, in -->
<!-- a file in alphabetic order of tagname. -->
<!-- ****************************************************** p -->
<tagDoc id=p usage=req>
<!-- The tagdoc identifier (p) is that used to refer to it. it must -->
<!-- be unique, and (for simplicity's sake) less than 8 chars long. -->
<!-- It need not be the same as the name of the element. The USAGE -->
<!-- attribute takes the values OPT (optional), MWA (mandatory when -->
<!-- applicable), REC (recommended), RWA (recommended when applicable), and REQ
<gi>p</gi>
<!-- The GI element specifies the name of the element and is mandatory, -->
<!-- even if it is the same as the name supplied as ID in the tagdoc. -->
<name>paragraph
<!-- The NAME element is optional, and contains a full English word or -->
<!-- phrase if the name is not itself self-explanatory -->
<desc>contains a prose paragraph.
<!-- The DESC element contains a phrase describing the function or -->
<!-- purpose of the element concerned. It should begin with a verb -->
<!-- and end with a fullstop. -->
<attlist>
</attlist>
<!-- The attlist element contains a specification for the attributes -->
<!-- which are unique to this element (in this case, none) -->
<exemplum><eg><![ CDATA [
<p>Hallgerd was outside. <q>There is blood on your
axe,</q> she said. <q>What have you done?</q></p>
<p><q>I have now arranged that you can be married a
second time,</q> replied Thjostolf.</p>
]]>
</eg>
<p>
This example shows very short paragraphs.</p>
<eg>
<!-- From Njal's saga, tr. Magnus Magnusson and -->
<!-- Hermann Palsson (Hammondsworth: Penguin, 1960, -->
<!-- rpt. 1979), chapter 12, p. 60. -->
</eg>
</exemplum>
<!-- The EXEMPLUM element contains an example for inclusion in the -->
<!-- reference manual (rather than the text of the chapter). You -->
<!-- can include short expository remarks within the EXEMPLUM element, -->
<!-- included within a P element, -->
<!-- as shown above, and you can have multiple EXEMPLUMs (sorry) -->
<!-- in one TAGDOC. -->
<remarks><p>In some contexts, the paragraph may have specialized meaning
(e.g. in the tag set for dictionaries, <gi>p</gi> is used to enclose any
running text, and thus does not imply text set off as is conventionally
done in running prose).
<!-- The REMARKS element contains any extra comment you think helpful -->
<!-- to understand how the element should be used. Like the EXEMPLUM, -->
<!-- its content is transferred to the reference manual but not the -->
<!-- chapter text. Its content must be enclosed, as here, in P tags, -->
<!-- even if there is only one paragraph. -->
<part type=base name=core>
<classes names=chunks>
<!-- PART and CLASSES are used during DTD construction; their proper use -->
<!-- requires a more detailed explanation of the ODD system than I have -->
<!-- space for here or you, probably, inclination to digest. Leave them -->
<!-- out, or supply them with default values (as here) -->
<datadesc>May contain character data and phrase-level elements.
<!-- The DATADESC specifies in words what kinds of content the element -->
<!-- may have: use a phrase like that above. -->
<elemdecl>- O (%soup;)
</elemdecl>
<!-- The ELEMDECL contains the meat of the SGML declaration for the -->
<!-- element concerned, as above. -->
<xref type=div2 target=p2.231>
<!-- Finally, you must include at least one XREF indicating the -->
<!-- section(s) of P2 in which the element is discussed. -->
</tagdoc>
<!-- There now follows a second example, showing how attributes are -->
<!-- specified, among other things. It is taken from the section of P2 -->
<!-- describing the Milestone tag. -->
<!-- First, here is the relevant taglist: -->
<p>Tags available for marking such section boundaries are:
<tagList>
<tagDesc tagDoc=milest atts='ed n unit'>
<tagDesc tagDoc=page.br>
<tagDesc tagDoc=line.br>
</tagList>
<!-- Note that this taglist will generate descriptions for three elements, -->
<!-- and for the first of these (that with the identifier MILEST) it will -->
<!-- include information about three attributes ED, N and UNIT. -->
<!-- There now follows the DTD fragment in the chapter for the milestone -->
<!-- tag. Note that it does not say anything explicit about its -->
<!-- attributes: these are generated automatically from the -->
<!-- tagdoc information with no further action on your part. -->
<p>The milestone tag has the following formal declaration:
<dtdFrag id=dmilest file=teicore2 n='Milestone tag'>
<tagdecl tagdoc=milest>
</dtdFrag>
<!-- There now follows the tagdoc information for the MILESTONE element; -->
<!-- to save space I have added comments only to the parts of it relating -->
<!-- to the attribute specifications. -->
<!-- ********************************************** milestone -->
<tagDoc id=milest usage=opt>
<gi>milestone</gi>
<desc>marks the boundary between sections of a text, as indicated by
changes in a standard reference system.
<attlist>
<!-- The ATTLIST element contains one or more ATTDEF elements, -->
<!-- each describing an attribute specific to this element -->
<!-- ..................................................... ed -->
<attDef id=ed usage=opt>
<attname>ed
<!-- As with TAGDOCs, an ATTDEF may have an ID (in this case ED) which -->
<!-- is unique, and must have an ATTNAME
<name>edition
<!-- It may also have an explanatory name... -->
<desc>indicates which edition or version the milestone applies to.
<!-- ... and must have a description, which follows the same rules -->
<!-- as the DESC on a TAGDOC. -->
<datatype>CDATA
<!-- The DATATYPE must be a SGML keyword valid as declared content -->
<!-- in an ATTLIST declaration i.e. CDATA, ID, IDREF, IDREFS etc. Or -->
<!-- it may be a namelist if the attribute value is taken from a closed -->
<!-- list. -->
<valdesc>Any string of characters; usually a siglum conventionally used
for the edition.
<!-- The VALDESC contains a brief description of the kind of value -->
<!-- the attribute may take, with any additional semantic constraints -->
<!-- as here. -->
<default>#REQUIRED
<!-- The DEFAULT must again be a valid SGML keyword, usually one of -->
<!-- #REQUIRED, #IMPLIED or an actual default value -->
<eg><![ CDATA [
]]>
</eg>
</attDef>
<!-- ...................................................... n -->
<attDef id=n usage=opt>
<attname>n
<name>number or name
<desc>indicates the new number or other value for the unit which changes
at this milestone.
<datatype>CDATA
<valdesc>Any string of characters.
<default>#IMPLIED
<remarks><p>The special value <term>unnumbered</term> should be used in
passages which fall outside the normal numbering scheme (e.g. chapter
heads, poem numbers or titles, or speaker attributions in verse drama).
</attDef>
<!-- ................................................... unit -->
<attDef id=unit usage=opt>
<attname>unit
<desc>indicates what kind of section is changing at this milestone.
<datatype>CDATA
<vallist type=semi>
<!-- In this example a VALLIST is given rather than a VALDESC, as the -->
<!-- values for this attribute are taken from a semi closed list, -->
<!-- as indicated by the DESC attribute. (Other possible values are -->
<!-- CLOSED for closed lists (for which the DATATYPE should also -->
<!-- include all the possible values as a namelist) and OPEN (the -->
<!-- default). -->
<val>page <desc>page breaks in the reference edition.
<val>column <desc>column breaks.
<val>line <desc>line breaks.
<val>book <desc>any units termed <cited>book</cited>,
<cited>liber</cited>, etc.
<val>poem <desc>individual poems in a collection.
<val>canto <desc>cantos or other major sections of a poem.
<val>stanza <desc>stanzas within a poem, book, or canto.
<val>act <desc>acts within a play.
<val>scene <desc>scenes within a play or act.
<val>section<desc>sections of any kind.
<val>absent <desc>passages not present in the reference edition.
</vallist>
<!-- The VALLIST contains paired VAL and DESC elements giving the -->
<!-- possible value and its intended meaning. -->
<default>#REQUIRED
<eg><![ CDATA [
]]>
</eg>
<remarks><p>If the milestone marks the beginning of a piece of text not
present in the reference edition, the special value <term>absent</term>
may be used as the value of <att>unit</att>. The normal interpretation
is that the reference edition does not contain the text which follows,
until the next <gi>milestone</gi> tag for the edition in question is
encountered.
<p>In addition to the values suggested, other terms may be appropriate
(e.g. <term>Stephanus</term> for the Stephanus numbers in Plato).
</attDef>
</attlist>
<exemplum><eg><![ CDATA [
<milestone ed=La name=Dreissiger n=23>
...
<milestone ed=La name=Dreissiger n=24>
...
]]>
</eg></exemplum>
<remarks><p>Milestones for page and column should precede
milestones for line numbers, but this and other logical requirements
cannot be enforced automatically by SGML; for better validation, a
concurrent markup stream should be used.
<part type=top name=core>
<classes>
<datadesc>May contain character data and phrase-level elements.
<elemdecl>- O EMPTY
</elemdecl>
<xref type=div3 target=p2.232ms>
</tagdoc>
<!-- That's all for now. Good luck! Really dedicated SGML hackers -->
<!-- will of course want to get hold of the ODD dtds and try validating -->
<!-- the stuff for themselves: we are entirely willing to make -->
<!-- these available to you -- but can't spare much time to explain -->
<!-- how they work in any detail. As aforesaid, clear drafts with -->
<!-- only minimal tagging will be very useful indeed; we are quite -->
<!-- happy to fix up the tagging to match our esoteric system -->
<!-- requirements. -->
Prepared by Robin Cover for The XML Cover Pages archive.
