-
Notifications
You must be signed in to change notification settings - Fork 1
/
part2-extensions.xml
720 lines (676 loc) · 32 KB
/
part2-extensions.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
<div xmlns:rng="http://relaxng.org/ns/structure/1.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:dbk="http://docbook.org/docbook-ng"
xmlns="http://www.tei-c.org/ns/1.0" xml:id="back-extensions"><!-- revised $Date$ -->
<head>Customizing the TEI</head>
<div>
<head>Introduction</head>
<p>This chapter describes how to produce a customisation of the TEI
P5 schema. From the start, the TEI was intended to be used as a set of
building blocks for creating a schema suitable for a particular
project. This is in keeping with the TEI philosophy of providing a
vocabulary for describing texts, not dictating precisely what those
texts must contain or might have contained. This means that it is
<emph>likely</emph>, not just <emph>possible</emph>, that you will
want to have a tailored view of the TEI.</p>
<p>What do we mean by a <soCalled>customisation</soCalled>? It is
important to understand that there is no single DTD or schema which is
the TEI; you must always choose which of the modules (there are
currently 22 of them, listed in <ptr target="#tab_modlist"/>) you
want, with the caveat that the three modules <ident>core</ident>,
<ident>header</ident> and <ident>textstructure</ident> (and
<ident>tei</ident>, when using RELAX NG) should always be chosen
unless you are doing something seriously arcane (elements in these
modules are referred to throughout the other modules in a promiscuous
fashion). But even when you have decided that, for instance, your
application will make use of <ident>msdescription</ident> and
<ident>linking</ident> modules, you may also want to
<list type="unordered">
<item>remove elements from some of the modules which you do not expect
to use (it often confuses peopled editing XML text when they are
offered too big a choice of elements)</item>
<item>rename elements (see <ptr target="#romai18n"/> for more discussion of
this)</item>
<item>add, delete or change (perhaps to make the datatype stricter)
attributes for existing elements
</item>
<item>add new elements, and insert them into the TEI class system</item>
</list>
We will be seeing examples of each of these in the following sections.</p>
<p>There are three ways of customising the TEI:
<list type="ordered">
<item>Writing a high-level specification for a view of the TEI, and generating
an <foreign>ad hoc</foreign> schema.
</item>
<item>Using the RELAX NG modules, and writing a wrapper schema.</item>
<item>Using the DTD modules, and specifying
in the document DTD subset which features you want activated. </item>
</list>
Let us stress again that there is <emph>no default schema or DTD</emph> for the TEI which you would
use normally. </p>
<p>It is not possible at present to use W3C Schema modules for customization.</p>
</div>
<div>
<head>Writing ODD specifications</head>
<p>The recommended way to customise the TEI is to write a formal
specification for your needs, as an XML document using TEI markup;
this can compiled into a suitable DTD, RELAX NG schema or W3C Schema,
using the <software>Roma</software> utilities. There are several
important reasons why this high-level method is recommended:
<list type="ordered">
<item>It is independent of the schema type (DTD, RELAX NG schema, W3C schema)</item>
<item>It lets you document your work using the familiar TEI markup.</item>
<item>It provides full access to the TEI class system.</item>
<item>The <software>Roma</software> utilities generate a single,
portable, schema file which you can transfer to other people without
worrying about link dependencies.</item>
</list>
The TEI markup used to write the specification is known as ODD (<hi>O</hi>ne
<hi>D</hi>ocument <hi>D</hi>oes it all<note place="foot">The concepts of ODD were
devised and implemented by Lou Burnard and Michael Sperberg-McQueen
early in the development of the TEI. The language developed over time as the TEI
was put together, and one form of it was documented in the TEI
Guidelines (versions 3 and 4); unfortunately, that version of the markup was not what
was actually used to write the TEI Guidelines, which diverged into a
more complex scheme. For version 5 of the TEI, the entire ODD language
was heavily revised and simplified by a working group led by Sebastian
Rahtz, and the Guidelines themselves brought into conformance with it.</note>
An ODD specification is a normal TEI XML document which makes use of
the <ident>tagdocs</ident> module. This adds a series of elements
which are used to specify a new schema, and modifications to the TEI
element structure. It is described in detail in
the TEI Guidelines chapter <title>Documentation Elements</title>, so
only a brief summary will be given here.</p>
<p>A TEI schema is defined by a <gi>schemaSpec</gi>
element containing an arbitrary mixture of explicit declarations for
objects (i.e. elements, classes, or macro specifications)
and references to other objects containing such declarations. In
simplified form, the data model is
<eg>schemaSpec =
(moduleRef | elementSpec | macroSpec | classSpec )*</eg>
where <gi>elementSpec</gi>, <gi>macroSpec</gi> and <gi>classSpec</gi>
contain definitions of TEI objects. <gi>moduleRef</gi> references groups
of existing definitions, in one of two ways:
<list type="ordered">
<item>If the <ident>key</ident> attribute is provided, it refers to
the TEI name for a module, and details of that are accessed from the
TEI web service database.</item>
<item>If the <ident>url</ident> attribute is provided, it refers to an
external file of schema definitions in the RELAX NG language (this is
used to pull in non-TEI schemas)</item>
</list>
</p>
<p>In the simplest case, a user-defined schema might simply combine
all the declarations from some nominated modules:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/odd1.xml"/>
</egXML>
An ODD processor, given such a document, would combine the
declarations which belong to the named modules, and deliver the result
as a schema of the requested type. It might also generate documentation for
all and only the elements declared by those modules.
The <ident>start</ident> attribute of <gi>schemaSpec</gi> is used to
specify in a RELAX NG schema which elements are valid entry points.</p>
<p>A schema might also include declarations for new elements, as in
the following example:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/odd1.5.xml"/>
</egXML>
A declaration for the element <gi>soundClip</gi>, which is not defined in the TEI
scheme, will be added to the output schema. This element will also be added to
the existing TEI class <ident>tei.data</ident>, and will thus be
avilable in TEI conformant documents.</p>
<p>There may also be re-declarations of existing elements,
by using the <ident>mode</ident> attribute on <gi>elementSpec</gi>,
<gi>classSpec</gi> or <gi>macroSpec</gi>. This can take four values
<list type="gloss">
<label>add</label><item>The object is entirely new. </item>
<label>replace</label><item>The object entirely replaces the existing
object with the same <ident>ident</ident>.</item>
<label>delete</label><item>All references to the original object with the same
<ident>ident</ident> are removed from the schema.</item>
<label>change</label><item>children elements of the
object which appear in the original specification are replaced by
the versions in the new specification. This may be at any level, as we
will see in examples below.</item>
</list>
For objects which are not new, you should specify the module in which
it was originally defined.<note>Strictly speaking, this is not needed,
but the current implementation of ODD tools relies on it.</note> It is
an error to provide <value>replace</value>, <value>delete</value> or
<value>change</value> versions for objects which do not already exist
in the TEI, and an error to add something with the same
<ident>ident</ident> attribute as an existing object in the TEI.</p>
<p>Specifing that we do not want some of the elements to appear in
our final schema is easy:
<egXML xmlns="http://www.tei-c.org/ns/Examples" url="examples/odds/odd2.xml"/>
Note that no child elements of the new object are indeed, or taken
notice of. </p>
<p>Defining new elements is not much more complicated. In the following example
we add a new element <gi>marriage</gi> which is modelled on the existing
<gi>birth</gi> element:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/odd4.xml"/>
</egXML>
There are usually four parts to such an
element definition:
<list type="ordered">
<item>An identifier (in this case the value <value>marriage</value> for
the <ident>ident</ident> attribute).</item>
<item>Documentation (the <gi>gloss</gi> and <gi>desc</gi>
elements)</item>
<item>Declaration of which classes this element is to be a member
(<ident>model.persEventLike</ident>,
<ident>att.editLike</ident>,
<ident>att.datable</ident>, and
<ident>att.naming</ident>—the same as <gi>birth</gi>)</item>
<item>The content model for the element, here the general purpose
pattern <ident>macro.phraseSeq</ident></item>
</list>
There is no need to specify a module for the element to appear in, as
this would not be used for anything.</p>
<p>What if the new element is to be in a different namespace?
A good example of this would be if you wanted to use the W3C XInclude
scheme in your XML. This is way of referring to external files to be
transcluded (DTD users will be familiar with the use of file entities
to perform this job). This document, for example, pulls in a
table (created by an automatic process) by using this piece of code:
<eg><![CDATA[<include href="examples/odds/modules.xml" xmlns="http://www.w3.org/2001/XInclude"/>]]></eg>
Since the <gi>include</gi> could occur anywhere, we want to add it to
a TEI class which is referenced almost everywhere;
<ident>tei.Incl</ident> does this job nicely. We could pull in an
external schema which defines <gi>include</gi>, but it may be amusing
to define it ourselves using this <gi>elementSpec</gi>:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/odd6.xml"/>
</egXML>
Note the new <ident>ns</ident> attribute on <gi>elementSpec</gi>
which says that this element is not to be defined in the default (TEI)
namespace, and the use of the shorthand RELAX NG method of inline
element definition of <gi>fallback</gi> within the <gi>include</gi>
element. </p>
<p>When we come to <emph>changing</emph> existing elements, the
specification looks a little more complex:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/odd3.xml"/>
</egXML>
In this example, we are changing the behaviour of the <gi>div</gi>
element so that the <ident>type</ident> attribute (inherited from the
class <ident>tei.divn</ident>) is mandatory and chosen from a fixed
set of values. The <value>change</value> value for <ident>mode</ident>
must be supplied on each identifiable part of the object which is to
change. So the <gi>elementSpec</gi> itself is in <value>change</value>
mode, plus the <gi>attDef</gi> for <ident>type</ident>, while the
<gi>valList</gi> is in <value>replace</value> mode. The elements we
have <emph>not</emph> specified any change for
(examples, references, etc) are copied from the
original.</p>
<p>Change mode can apply to classes as well as elements. In the
following example, we remove a set of attributes which are provided
for any element which is a member of the <ident>tei.linking</ident> class:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/odd5.xml"/>
</egXML>
If you want to change which elements <emph>belong</emph> to
<ident>tei.linking</ident>, you must change the <gi>classes</gi>
element of each of the elements separately.</p>
<p>What do you do when you have composed your ODD specification?
Now you can turn it into schemas or DTDs for use with XML editors or
validators (the <soCalled>tangle</soCalled> process, in the jargon of
literate programming), or create schema documentation showing the
specification for your elements and classes (the
<soCalled>weave</soCalled> process). Both of these tasks are the job
of the <software>Roma</software> family of software. This consists of
a set of XSLT transformations to manipulate ODD XML files, a script to
run them in the right way (see <ptr target="#romacommandline"/>),
and a form-filling web application (see <ptr
target="#romaweb"/>) to help you develop the ODD XML
and run the transformations.</p>
</div>
<div>
<head>Working with RELAX NG schema modules</head>
<p>If you want to use the RELAX NG schema modules,<note
place="foot">Examples of RELAX NG in this section are presented
using the compact syntax; when you write TEI customisations in the
next section, it will be necessary to use the XML syntax.</note> you must always
write a wrapper schema, selecting the appropriate modules. Thus a minimal TEI
schema might look like this:
<eg>
<xi:include href="examples/odds/minimal.rnc" parse="text"/>
</eg>
This is clearer than the DTD method, as it loads files
containing definitions from explicit URLs. It is then possible to override
any patterns in the included files; so the following schema
<eg>
<xi:include href="examples/odds/minimal2.rnc" parse="text"/>
</eg>
loads the <ident>header</ident> module, but then redefines the meaning of
<gi>mentioned</gi> to be the special RELAX NG pattern
<kw>notAllowed</kw>. This is a powerful and elegant mechanism; the
only downside is that you must understand the inner structure of the
TEI modules.</p>
<p>RELAX NG patterns are defined for the TEI as follows:
<list type="unordered">
<item>Each element, macro and class identifies the module it is part
of; this determines which schema file its definition is written to.</item>
<item>Every macro (defined by a <gi>macroSpec</gi> in the source) has
a RELAX NG pattern of the same name. e.g.
<eg>macro.glossSeq = altIdent?, equiv*, gloss?, desc?</eg>
This can be redefined as desired.
</item>
<item>Class specifications generate a number of patterns, depending on
their type:
<list type="ordered"><item>An attribute class generates a pattern which references
the definition of each of the class attributes.</item>
<item>Each attribute generates a pattern.</item>
<item>A model class generates a pattern with an initial value of
<kw>notAllowed</kw></item>
</list>
Thus the <ident>tei.timed</ident> attribute class generates
<eg>
<xi:include href="examples/odds/classdef.rnc" parse="text"/>
while the
</eg>
<ident>tei.lists</ident> model class generates
<eg>tei.lists = notAllowed</eg>
</item>
<item>Every element generates at least three patterns; the first
defines the element itself, the second defines its content, and the third its
attributes. For example, the top-level element <gi>TEI</gi> is defined with:
<eg>
<xi:include href="examples/odds/elemdef.rnc" parse="text"/>
</eg>
Each of these can be redefined
separately. In addition, for each model class of which the element is
a member, it generates an addition to the class pattern. Thus
<gi>biblItem</gi> is a member of the
<ident>tei.bibl</ident>,
<ident>tei.declarable</ident>, and
<ident>tei.typed</ident> classes, so it produces:
<eg>
<xi:include href="examples/odds/elemdef2.rnc" parse="text"/>
</eg>
so that any reference to <code>tei.bibl</code> will now allow for
<gi>biblItem</gi> too.
</item>
</list>
</p>
<p>If you intend to make extensive use of the TEI in conjunction with
other schemas written in RELAX NG, working directly with the RELAX NG
modules is probably the best skill to learn. If you intend to work
solely within the confines of the TEI, and need to use DTDs and W3C
Schema as well as RELAX NG, writing customisations in the
TEI's own language is better.</p>
</div>
<div>
<head>Working with the DTD subset</head>
<p>If you use DTDs, you specify which modules of the TEI you want
to use by means of the DTD internal subset. A minimal TEI
document using this method might start as follows:
<eg><![CDATA[<!DOCTYPE TEI SYSTEM "http://www.tei-c.org/schema/dtd/p5/tei.dtd" [
<!ENTITY % TEI.header "INCLUDE">
<!ENTITY % TEI.core "INCLUDE">
<!ENTITY % TEI.textstructure "INCLUDE">
]>
<TEI xmlns="http://www.tei-c.org/ns/1.0">]]></eg>
This loads the obligatory modules <ident>header</ident>,
<ident>core</ident>, and <ident>textstructure</ident> by setting the
corresponding parameter entity to <kw>INCLUDE</kw>.
</p>
<p> There is a parameter entity for each module (created by prefixing
the module name with <code>TEI.</code>, so we could request
the <ident>linking</ident> module to be loaded by adding
<eg><![CDATA[<!ENTITY % TEI.linking "INCLUDE">]]></eg> to the DTD
subset. It is also possible to disable particular elements from the
modules by setting a parameter corresponding to the element. So
<eg><![CDATA[<!ENTITY % ab "IGNORE" >]]></eg> would remove
<gi>ab</gi> from the list of allowed elements. Although this type of
customisation is useful, it is not possible to use the method to add
new elements, change attributes, or manipulate classes. That sort of
change requires a deeper understanding of writing DTD extensions,
beyond the scope of this introduction.</p>
</div>
<div>
<head>Making use of non-TEI schemas</head>
<p>The TEI was designed to capture all the vagaries of literary and
linguistic <emph>text</emph>; it does not attempt to copy the work of other
specialised descriptive languages, such as those for chemistry,
mathematics, and vector graphics, or the technical vocabulary of
fields like law, health care and computer science. Some of these areas
have been addressed as thoroughly as the TEI in their own
standards. The recommended way to work is to write composite
documents, mixing material from the different namespaces.
</p>
<p>Two common cases which do not require any interleaving or redefinition
of another namespace are:
<list type="ordered">
<item>redefining the content of <gi>formula</gi> to
allow for MathML markup.</item>
<item>redefining the content of <gi>figure</gi> to allow SVG
markup.</item>
</list>
In each case, we first need a <gi>moduleRef</gi> which loads the
external schema in RELAX NG format:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<moduleRef url="mathml2-main.rng"/>
<moduleRef url="svg-main.rng"/></egXML>
These schemas can be downloaded from <ptr target="http://somewere/mathML"/>
and <ptr target="http://somewere/SVG"/>; note that they each need a small
fix to remove the RELAX NG <gi>start</gi> pattern, as this causes a conflict with
the TEI definition. These define respectively two patterns called
<kw>mathml.math</kw> and <kw>svg.svg</kw>, which we can proceed to add to TEI
content models.
<list type="unordered">
<item>For MathML, we can redefine an existing macro which
is already provided as a hook inside the content of <gi>formula</gi>:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/addmath.xml"/>
</egXML>
</item>
<item>For SVG, we need to change the model of <gi>figure</gi>, simply
adding a reference to <kw>svg.svg</kw> at the end of a <gi>choice</gi> list:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/addsvg.xml"/>
</egXML>
</item>
</list>
</p>
<p>What if we want to write a composite document mixing
material from two fields? Since all the TEI elements are in their own
XML namespace, it is easy to write a document which interleaves TEI
markup with markup from another namespace, as in this example of TEI
and Docbook:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<p>The button on our web page has the current date on it:
<dbk:guibutton>
<date calendar="Julian" value="1732-02-22">Feb. 11, 1731/32, O.S.</date>
</dbk:guibutton>
or at least the date on which we last updated it.</p>
</egXML>
But can we validate this XML against a schema? Using the
Namespace Routing Language, we can validate the two languages
separately:<note>This examples use the notation supported by
<software>jing</software> for expressing NRL rules.</note>
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<rules xmlns="http://www.thaiopensource.com/validate/nrl">
<namespace ns="http://www.tei-c.org/ns/1.0">
<validate schema="testtei.rng"/>
</namespace>
<namespace ns="http://docbook.org/docbook-ng">
<validate schema="docbook.rng"/>
</namespace>
</rules>
</egXML>
Although this does the checking of the separate grammars properly,
it still gives errors at the intersections, so we
we also need a TEI customisation which checks where insert of
<soCalled>foreign</soCalled> elements is permitted.
This means importing another schema, and changing one or more TEI
classes to allow for the new element(s). If it is also required that
TEI elements be allowed inside the elements of the other namespace,
we also have to modify the other namespace. This can be achieved
manually in ODD if you have some knowledge of RELAX NG,
using the optional <gi>content</gi> child of <gi>moduleRef</gi>.
It is an error to supply this element unless the <gi>moduleRef</gi>
has a <ident>url</ident> attribute accessing an external
schema. A simple case would be this schema:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<schemaSpec ident="testdocbook1" start="">
<moduleRef key="header"/>
<moduleRef key="core"/>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef url="docbook.rng">
<content>
<rng:define name="tei.lists" combine="choice">
<rng:ref name="db.qandaset"/>
</rng:define>
<rng:start combine="choice">
<rng:ref name="TEI"/>
</rng:start>
</content>
</moduleRef>
</schemaSpec>
</egXML>
The Docbook schema is included, and the redefinition of
<ident>tei.lists</ident> to add Docbook's <value>db.qandaset</value>
is supplied as the content of the <gi>moduleRef</gi>. Note also that
since Docbook defines a RELAX NG <gi>start</gi> elements, we tell the
ODD
<gi>schemaSpec</gi> to generate nothing, and add <gi>TEI</gi> to the
Docbook one. </p>
<p>A more complex schema redefines both TEI and Docbook patterns,
allowing Docbook inline elements to occur where the TEI allows
<ident>tei.hqphrase</ident>, and members of the
<ident>tei.data</ident>
class to occur where Docbook allows <ident>gui.inlines</ident>:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<schemaSpec ident="testdocbook5" start="">
<moduleRef key="header"/>
<moduleRef key="core"/>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef url="docbook.rng">
<content>
<rng:define name="docbook.text" combine="choice">
<rng:ref name="tei.data"/>
</rng:define>
<rng:define name="tei.hqphrase" combine="choice">
<rng:ref name="gui.inlines"/>
</rng:define>
<rng:start combine="choice">
<rng:ref name="TEI"/>
</rng:start>
</content>
</moduleRef>
</schemaSpec>
</egXML>
This allows for our interleaving example to be valid.</p>
<p>
Note that these mixed-namespace techniques produce schemas which
<software>roma</software> may not translate very well to W3C Schema;
in that language, elements from different namespaces have to be in
different
schema files, so one mixed-namespace RELAX NG schema translates to
multiple <code>.xsd</code> files which have to be managed.</p>
</div>
<div xml:id="romai18n">
<head>Internationalisation</head>
<p>A common requirement for changing existing elements is
to make the visible names suit a local language.
If we want to use the TEI in, e.g., an entirely Spanish-speaking
environment, it can be useful to have a copy of the TEI schema
with all the names converted to Spanish. Documents can be created
and edited using this schema, and then translated back to the
canonical form for long-term archiving or distribution.</p>
<p>These translations are possible because the TEI
defines names in English for elements and attributes, but does not use
these names directly in content models for other elements. This means
that the names can be changed without breaking the rest of the
system. For example, the content model for <gi>lg</gi> is
<eg>lg.content =
(model.divTop | model.global)*,
(model.lLike | lg),
(model.lLike | lg | model.global)*,
(model.divBottom, model.global*)*</eg>
but the <q>l</q> here refers to the <emph>pattern</emph> called
<q>l</q>; this is defined with:
<eg>l = element l { l.content, l.attributes }</eg>
If we change it to
<eg>l = element verso { l.content, l.attributes }</eg>
the definition for <gi>lg</gi> will still work, and the pointers
to the content and attributes of <q>l</q> remain correct. </p>
<p>If we create documents using this schema, how can we be
sure the back translation is easy? Because all TEI elements carry
with them a hidden attribute which stores the original name.</p>
<p>The translation process in ODD is simple. Each element or attribute
affected must be supplied in <kw>change</kw> mode, with simply
an <gi>altIdent</gi> provided. For example, here are some translations
into Spanish:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<xi:include href="examples/odds/spanish.xml"/>
</egXML>
Notice that each <gi>attDef</gi> element must also specify
<kw>change</kw> mode, as well as the parent <gi>elementSpec</gi>.</p>
<p>Constructing specifications like this by hand is both tedious and
error-prone, and it would be unwise for each separate project to make
its own translations. The TEI Consortium therefore maintains a set of
translated names<note place="foot">A projected initiated by Alejandro
Bia, and extended by Sebastian Rahtz and Arno Mittelbach.</note> (at
the time of writing, into Spanish, Catalan, French (partial) and
German), and a utility to generate the appropriate ODD code for
elements from all the modules you have selected. The
<software>Roma</software> application automates this to choosing from a drop
down list (<ptr target="#roma_lang_select"/>).
<figure xml:id="roma_lang_select">
<graphic width="6in" url="examples/odds/roma_lang_select.png"/>
<head>Choosing language for names in <ident>Roma</ident></head>
</figure>
The effect of using a translated schema is shown in <ptr
target="#oxygen_edit_spanish"/>; the <ident>oXygen</ident> editor is
shown editing <title>Hamlet</title> with Spanish element and attribute
names. Note that the documentation of the names which
<ident>oXygen</ident> displays is still in English—this is harder to
get translated fully.
<figure xml:id="oxygen_edit_spanish">
<graphic width="6in" url="examples/odds/oxygen_edit_spanish.png"/>
<head>Editing TEI text using a schema translated to Spanish</head>
</figure>
</p>
</div>
<div xml:id="romacommandline">
<head>Roma (command line)</head>
<p>An ODD specification can be processed in a scripting environment
by using the <software>roma</software> command-line script. This takes
the form:
<eg>
Usage: roma [options] schemaspec [output_directory]
options, shown with defaults:
--xsl=/usr/share/xml/tei/stylesheet
--teiserver=http://tei.oucs.ox.ac.uk/Query/
options, binary switches:
--doc # create expanded documented ODD
--nodtd # suppress DTD creation
--norelax # suppress RELAX NG creation
--noxsd # suppress W3C XML Schema creation
--debug # leave temporary files, etc.
</eg>
By default the script creates DTD, XSD and RELAX NG schemas, each
of these can be suppressed if needed, and a set of summary
documentation can be created. The <ident>xsl</ident> and
<ident>teiserver</ident>
options point to resources which <software>roma</software> needs to do
its job; if you have a local copy of the TEI XSL stylesheets, or a
local TEI eXist database, you can make the script independent of web access.
</p>
</div>
<div xml:id="romaweb">
<head>Roma (web application)</head>
<p>The Roma web application provides a way to specify what you want in
an ODD specification without having to write the XML code. It does
not cover everything which is possible in the ODD language, but should
provide a convenient interface for most tasks.</p>
<p>Roma can be initialized with a suggested minimal ODD specification,
or from an existing ODD XML file. This allows you to do some work with
Roma, save the state of the ODD specification, and then reload it for
more changes in a later session. <ptr target="#roma_start"/> shows
the initial dialogue.</p>
<p>The main Roma screen lets you choose
between nine activities:
<list type="gloss">
<label>New</label><item>Start a new schema specification.</item>
<label>Save</label><item>Save the current state of the specification
(you will be prompted for a file name to save it as; the suggested
name is taken from the <ident>ident</ident> attribute of the
<gi>schemaSpec</gi>, which defaults to <value>myTei</value>.</item>
<label>Customize </label><item>As shown in <ptr
target="#roma_customize"/>, this screen lets you specify metadata
about the schema (name, authorship, licensing) and the language in
which you want Roma to operate (for example, <ptr
target="#roma_in_french"/>
shows Roma in French).</item>
<label>Modules</label><item>Set and maintain the modules which
will be included in the schema; <ptr target="#roma_modules"/>
shows the schema with the standard modules, plus manuscript
description. If you click on a module name, you can edit a list of the
elements which appear in that module (<ptr
target="#roma_change_module"/>), marking them to be included or
excluded from the schema; clicking in the rightmost link next to each
element lets you edit the attributes for that element.</item>
<label>Add Elements</label>
<item>Create a new element (<ptr target="#roma_add_element"/>); note
that when you come to specify the content model of the element, you
can choose to reference any of the existing macros, one of the model
classes,
or construct your own in RELAX NG XML syntax. The TEI classes and
macros are explained in a little more detail in <ptr
target="#classes"/>
and <ptr target="#macros"/>.
You have to create each attribute separately (<ptr target="#roma_new_attribute"/>).</item>
<label>Change Classes</label><item>List the attribute classes
(<ptr target="#roma_change_class_atts"/>).
If you click on the name of a class, the standard TEI
Guidelines documentation for it is displayed (<ptr
target="#roma_show_class"/>);
clicking the link on the right lets you edit the attributes for that
class (<ptr target="#roma_edit_class_atts"/>).</item>
<label>Language</label><item>Select the language for automatic
internationalisation (see <ptr target="#romai18n"/>).</item>
<label>Schema</label><item>Create a schema (<ptr
target="#roma_schema_select"/>); you can choose between Relax NG
(XML syntax), Relax NG (compact syntax), W3C Schema, and DTD.</item>
<label>Documentation</label><item>Weave the ODD specification into
documentation in a variety of formats (<ptr target="#roma_generate_doc"/>).</item>
<label>Help</label><item>Turn on help for each screen.</item>
</list>
</p>
<figure xml:id="roma_start">
<head>Roma: opening dialogue</head>
<graphic width="6in" url="examples/odds/roma_start.png"/>
</figure>
<figure xml:id="roma_customize">
<head>Roma: schema customisation summary</head>
<graphic width="6in" url="examples/odds/roma_customize.png"/>
</figure>
<figure xml:id="roma_modules">
<head>Roma: selecting modules</head>
<graphic width="6in" url="examples/odds/roma_modules.png"/>
</figure>
<figure xml:id="roma_change_module">
<head>Roma: changing elements in a module</head>
<graphic width="6in" url="examples/odds/roma_change_module.png"/>
</figure>
<figure xml:id="roma_add_element">
<head>Roma: adding a new element</head>
<graphic width="6in" url="examples/odds/roma_add_element.png"/>
</figure>
<figure xml:id="roma_show_class">
<head>Roma: display of class details</head>
<graphic width="6in" url="examples/odds/roma_show_class.png"/>
</figure>
<figure xml:id="roma_change_class_atts">
<head>Roma: changing attribute classes</head>
<graphic width="6in" url="examples/odds/roma_change_class_atts.png"/>
</figure>
<figure xml:id="roma_edit_class_atts">
<head>Roma: editing class attributes</head>
<graphic width="6in" url="examples/odds/roma_edit_class_atts.png"/>
</figure>
<figure xml:id="roma_new_attribute">
<head>Roma: adding a new attribute</head>
<graphic width="6in" url="examples/odds/roma_new_attribute.png"/>
</figure>
<figure xml:id="roma_schema_select">
<head>Roma: selecting output schema language</head>
<graphic width="6in" url="examples/odds/roma_schema_select.png"/>
</figure>
<figure xml:id="roma_generate_doc">
<head>Roma: generating documentation (choice of formats)</head>
<graphic width="6in" url="examples/odds/roma_generate_doc.png"/>
</figure>
<figure xml:id="roma_in_french">
<head>Roma: interface in French</head>
<graphic width="6in" url="examples/odds/roma_in_french.png"/>
</figure>
</div>
</div>