4. Divisions, Paragraphs, Lists and Other Block Elements
Text divisions are encoded in div. Each division must have a head containing the heading for this division. Headings should just contain the ‘bare’ heading, without numbering or other labels; those are added automatically when the TEI source file is rendered.
Divisions typically consist of a number of paragraphs, inside p elements. Apart from paragraphs, they can contain following text structures:
- subdivisions
- lists
- quotations
- figures and graphics
- tables
- code examples
Divisions can nest, by simply including a new div element with an xml:id attribute and a head in a parent division. There's no need to indicate the nesting level for subdivisions: this is determined from the structural encoding by the rendering scripts. Please note that the general TEI limitations hold: divisions may not be followed by ‘bare’ paragraphs. In order to facilitate cross-referencing, you are encouraged to provide a unique identification code in an xml:id attribute for each div.
Following example illustrates a text division in which two introductory paragraphs are being followed by two more subdivisions.
<body>
<div xml:id="notodd">
<head>What’s not ODD?</head>
<p>In the current source of TEI P5, there is extensive use of several different
XML vocabularies: <list rend="bulleted">
<item>Examples in TEI P5 are presented as if they belonged to some other
<soCalled>TEI Example Namespace</soCalled>;</item>
<item>Element content models are expressed using a subset of RELAX NG, as
discussed in the previous section;</item>
<item>Datatypes are expressed in a variety of ways, mapping either to built-in
W3C datatypes (as defined in the W3C Schema Language) or to RELAX NG
constructs;</item>
<item>Additional semantic constraints (for example, co-dependence of
attributes and element content) are expressed using ISO Schematron
rules.</item>
</list>
</p>
<p>Everything else in a TEI-conformant ODD specification uses only constructs from
the TEI namespace. In this paper, we will argue for a further extension of the
ODD language to replace several of the cases listed above.</p>
<div xml:id="elementcontentmodels">
<head>Element Content Models</head>
<p>ODD was originally intended to support the <emph>intersection</emph> of the
content models definable using three different schema languages. In practice,
this reduced our modeling requirements quite significantly.
</p>
</div>
<div xml:id="datatyping">
<head>Datatyping and Other Forms of Validation</head>
<p>Validation of an element’s content model is but one of many different layers
of validation that a TEI user may wish to express in their ODD specification.
</p>
</div>
</div>
</body>
Paragraphs are encoded with
p elements. They are the main building blocks of a division. They can contain plain text, mixed with other structural elements:
<p>Thus we introduce the <gi>transferGrp</gi> element, a grouping element somewhat
like <gi>surfaceGrp</gi> but, like <gi>altGrp</gi> or <gi>attList</gi>, with
the ability to assert the relationship among its children rather than just common
features. This is accomplished with an <att>org</att> attribute whose suggested
values include:
<list type="gloss">
<label>
<val>group</val>
</label>
<item>an unordered set</item>
<label>
<val>sequence</val>
</label>
<item>a (chronologically) ordered set</item>
<label>
<val>choice</val>
</label>
<item>only one of the child <gi>transfer</gi>s
obtained</item>
</list>
</p>
<p>The following example demonstrates the use of <gi>transferGrp</gi> to indicate a
transaction which is attested in (at least) two source documents which disagree as to
the amount of money involved.</p>
Lists in jTEI are relatively simple. They are encoded in a list element and differentiated by the type attribute, which may have only one value, gloss. <list type="gloss"> is (as you might expect) a glossary list, and must consist of a sequence of labels and items, like this:
<list type="gloss">
<label>compressor</label>
<item>a device which reduces the peaks of volume in an audio signal</item>
<label>equalizer</label>
<item>a device which allows different frequency bands in an audio signal
to be cut or boosted</item>
</list>
All other types of list (numbered, bulleted etc.) do not have the
type attribute. Their appearance is controlled by the
rend attribute:
- list contains any sequence of items organized as a list.
| rend | describes the way the list should be rendered. |
Lists may be nested:
<list rend="bulleted">
<item>compressor:
<list rend="ordered">
<item>limiter</item>
<item>multiband compressor</item>
</list>
</item>
<item>equalizer:
<list rend="ordered">
<item>graphic equalizer</item>
<item>parametric equalizer</item>
</list>
</item>
</list>
For processing reasongs, jTEI puts one restriction on what can appear inside lists: you can't use table anywhere inside item.
The main components of a quotation are the quoted text itself, and a reference to the source it was quoted from. The quoted text is encoded with a
quote element, without quotation marks. Quotations marks are added automatically by the rendering scripts. The jTEI schema requires that each quotation is linked to a bibliographic reference, identifying the source from where the text has been quoted. Typically, the source of a quotation is listed in the bibliography at the end of the article. References to such sources are encoded in a
ref element, with a
type attribute of value
bibl, whose
target attribute must point to the
xml:id value of a
bibl element in the article's bibliography. You must provide an
xml:id attribute for the
ref element itself. This makes it possible to connect the quotation with its specific reference via the
source attribute on the
quote element:
<p>In his blog post, <title level="a">Text: A Massively Addressable Object</title>,
published in the 2012 anthology <title level="m">Debates in the Digital
Humanities</title>, Michael Witmore defines texts as objects that are
<quote source="#quoteref3">massively addressable at different levels of scale</quote>
(<ref type="bibl" xml:id="quoteref3"
target="#witmore12">Witmore 2012, 325</ref>).
</p>
Here, we see how the value #quoteref3 for the source attribute expresses the correspondence with the bibliographic reference in <ref type="bibl" xml:id="quoteref3" target="#witmore12">Witmore 2012, 325</ref>.
In some cases, quotations are taken from ‘less bibliographic’ sources, such as email conversations and other non-published texts. Such sources are not listed in the bibliography, so you can't refer to them with a
<ref type="bibl"> reference. Instead, you should include the description of the source in the text. The description should be encoded in a
bibl element with an
xml:id attribute. You should link the quotation to this bibliographic description by pointing to this
xml:id attribute with the
source attribute of the
quote element:
<p>An exchange on the TEI electronic mailing list sparked the research published
in this article, when a community expert wrote that given
<quote source="#quoteref1">a graduate student in English who has heard about TEI
and wants to dip her toes into it because she thinks it may be a better way of
putting on the Web some 17th century poems<gap/> Where does she go for help?
Where in the TEI universe is the level of ubiquitous Grade I support?</quote>
(<bibl xml:id="quoteref1">Martin Mueller, pers. comm, Jan. 18, 2013</bibl>).</p>
Here, the
#quoteref1 value for the
source attribute on
quote points to the
bibl element in the text, describing the ‘less bibliographic’ source for the quotation in a footnote.
Note how the examples above were inline quotations, which will be rendered inside the running text of the paragraph they appear in. It is also possible to encode block quotations, by wrapping the
quote and its
ref inside a
cit container. A
cit element can occur either in or between paragraphs, but is always rendered as a blockquote:
<p>In <title level="a">Wampum as Hypertext</title>, Angela Haas complicates the
distinction between technology and high technology by discussing the way wampum
belts function the same as Western hypertexts. Haas contends that while there are
many similarities, they differ when we understand the way wampum is reliant on
cultural practices and memory:
<cit>
<quote source="#quoteref8">Consequently one could argue that wampum is limited
in relation to contemporary Western hypertexts in that it requires human
intervention to remember the intent and content of the original message; however,
one could also posit that such interaction encourages continuous civic involvement
instead of an over-reliance on technology.</quote>
<ref type="bibl" xml:id="quoteref8"
target="#haas07">Haas 2007, 93</ref>
</cit>
</p>
The cit element has been constrained in jTEI so it can only contain quote, ref, and bibl.
Inside quotations, inline rhetorical elements can be used (see 5. Inline Rhetorical Elements). Two of such elements are quite specific to quotations, in the context of a jTEI article, however, namely omissions and supplied text. Omissions are encoded with gap, which at rendering time is transformed to the typographic omission symbol: …1. If you supply text that wasn't present in the original quotation, you should wrap the supplied text in a supplied element. At rendering time, the supplied start and end tags are replaced with the [ and ] characters, respectively.
Apart from quote for ‘attributed’ quotations, you can also use q for short ‘anonymous’ inline quotations, whose source is not known or irrelevant. This is discussed in more detail in 5. Inline Rhetorical Elements.
Example computer code in jTEI falls into two categories. XML code appears in the <egXML xmlns="http://www.tei-c.org/ns/Examples"> element. When you use this element, make sure you get the namespace right; all elements appearing in the egXML element are also in the Examples namespace, to distinguish them from regular TEI elements that are part of the encoding of the document. Code from non-XML languages appears in the eg element.
In many cases, example code will appear inline as part of the prose of your article
2:
<p>Links between authors and books are encoded using <gi>link</gi> elements: <egXML
xmlns="http://www.tei-c.org/ns/Examples"> <link target="#middlemarch #eliot"/>
</egXML> </p>
You might want to provide a caption for code examples. In these cases, the
eg or
egXML element should be enclosed in a
figure:
<figure xml:id="example_code_1">
<eg> declare function local:getTitles($source as element(div)) as xs:string*{
for $t in $source//title
return xs:string($t)
};
</eg>
<head type="legend">A simple XQuery function</head>
</figure>
At rendering time, captions of examples will be supplied with a leading
‘Example X’, where X is the number of the example. You can link to and refer to block examples like this
using <ref> and <ptr>. In order to do so, you should provide a unique identification code to the
figure in an
xml:id attribute.
Tables can be encoded with the table element. Tables consist of a number of rows (row) that contain a number of cells (cell). Header rows and cells can be distinguished by different values for the type attribute:
- label
- The row or cell contains a header, not actual data.
- data
- (default) The row or cell contains data.
Cells and rows can be merged. In order to indicate how many columns a row or cell spans, a number can be provided for a cols attribute; the number of rows spanned can be given as value for a rows attribute.
<table xml:id="table1">
<head>Elements in <ident>tei_corset</ident> customization</head>
<row role="label">
<cell>Module</cell>
<cell>Elements in <ident>tei_corset</ident>
</cell>
</row>
<row>
<cell role="label">
<ident>textstructure</ident>
</cell>
<cell>
<gi>body</gi>
<gi>div</gi>
<gi>TEI</gi>
</cell>
</row>
<row>
<cell role="label">
<ident>figures</ident>
</cell>
<cell>
<gi>cell</gi>
<gi>row</gi>
<gi>table</gi>
</cell>
</row>
<row>
<cell cols="2">a sample cell spanning two columns (this was not in the original)</cell>
</row>
</table>
The example above illustrates how the first row is marked as a header row with <row role="label">, and how the left column is marked as a header column by specifying each first cell in a row as <cell role="label">. The last cell illustrates how column spanning can be indicated with <cell cols="2">.
Note how the example also illustrates how tables can have headings, in a head element. The text of this heading should not begin with ‘Table 1’ or any similar prefix; this will be provided when the article is rendered. To link to the table, all you need to do is to provide a pointer targeting its xml:id attribute:
<p>As you can see from <ptr target="#table1" type="crossref"/>, the elements included...</p>
This will be expanded at rendering time into ‘Table X’, where X is the appropriate table number.