CETEIcean 1.3.0 → 1.6.0
Sign up to get free protection for your applications and to get access to all the features.
- package/.vscode/settings.json +6 -0
- package/README.md +8 -0
- package/package.json +6 -5
- package/rollup.config.js +2 -2
- package/src/CETEI.js +22 -8
- package/src/behaviors.js +5 -0
- package/src/dom.js +4 -0
- package/src/utilities.js +6 -1
- package/test/TCW22.html +16 -2
- package/test/addBehaviorTest.html +2 -2
- package/test/tcw20.html +960 -0
- package/tutorial_en/README.md +3 -1
- package/tutorial_es/README.md +104 -25
- package/tutorial_es/screenshots/ceteicean_es1.png +0 -0
- package/tutorial_es/screenshots/ceteicean_es2.png +0 -0
- package/tutorial_es/screenshots/ceteicean_es3.png +0 -0
- package/tutorial_es/screenshots/ceteicean_es4.png +0 -0
- package/tutorial_es/screenshots/ceteicean_es5.png +0 -0
- package/xslt/make-CETEIcean-3.xsl +81 -0
- package/xslt/make-CETEIcean.xsl +2 -2
package/test/tcw20.html
ADDED
|
@@ -0,0 +1,960 @@
|
|
|
1
|
+
<!DOCTYPE html><html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><link rel="stylesheet" href="https://teic.github.io/css/tei.css"><script type="text/javascript" src="../dist/CETEI.js"></script></head><body>
|
|
2
|
+
<!--
|
|
3
|
+
$LastChangedDate: 2011-12-06$.
|
|
4
|
+
$LastChangedBy: martindholmes$
|
|
5
|
+
$LastChangedRevision: 8769 $
|
|
6
|
+
--><?xml-model href="https://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"><?xml-model href="https://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"><tei-tei data-xmlns="http://www.tei-c.org/ns/1.0" data-origname="TEI">
|
|
7
|
+
<tei-teiheader data-origname="teiHeader">
|
|
8
|
+
<tei-filedesc data-origname="fileDesc">
|
|
9
|
+
<tei-titlestmt data-origname="titleStmt">
|
|
10
|
+
<tei-title data-origname="title">How to edit the TEI Guidelines</tei-title>
|
|
11
|
+
<tei-author data-origname="author">Lou Burnard</tei-author>
|
|
12
|
+
</tei-titlestmt>
|
|
13
|
+
<tei-publicationstmt data-origname="publicationStmt">
|
|
14
|
+
<tei-publisher data-origname="publisher">Text Encoding Initiative</tei-publisher>
|
|
15
|
+
<tei-date data-origname="date">2011</tei-date>
|
|
16
|
+
</tei-publicationstmt>
|
|
17
|
+
<tei-sourcedesc data-origname="sourceDesc">
|
|
18
|
+
<tei-p data-origname="p">All my own work</tei-p>
|
|
19
|
+
</tei-sourcedesc>
|
|
20
|
+
</tei-filedesc>
|
|
21
|
+
<tei-revisiondesc data-origname="revisionDesc">
|
|
22
|
+
<tei-change data-origname="change" data-origatts="when who" when="2020-02-10" who="EBB">Adding guidance on how to provide supporting explanation with remarks and with paragraphs within exempla.</tei-change>
|
|
23
|
+
<tei-change data-origname="change" data-origatts="when who" when="2020-02-03" who="MS">Changed link to TCW 24.</tei-change>
|
|
24
|
+
<tei-change data-origname="change" data-origatts="when who" when="2019-12-26" who="EBB">Revised explanation of how to work in repo branches other than dev branch.</tei-change>
|
|
25
|
+
<tei-change data-origname="change" data-origatts="when who" when="2018-09-16" who="MDH">Linked to schema that actually exists, and tweaked to handle the fallout.</tei-change>
|
|
26
|
+
<tei-change data-origname="change" data-origatts="when who" when="2018-09-16" who="MDH">Adding documentation on how to create or edit an Appendix to the Guidelines.</tei-change>
|
|
27
|
+
<tei-change data-origname="change" data-origatts="when who" when="2016-07-08" who="MDH">Adding more documentation to clarify where some processing instructions in the Guidelines are actually processed.</tei-change>
|
|
28
|
+
<tei-change data-origname="change" data-origatts="when who" when="2015-12-14" who="MDH">Updates to account for new Jenkins server subdomains.</tei-change>
|
|
29
|
+
<tei-change data-origname="change" data-origatts="when who" when="2015-11-10" who="MDH">Updates to account for the change from master to dev branch on GitHub.</tei-change>
|
|
30
|
+
<tei-change data-origname="change" data-origatts="when who" when="2015-10-03" who="MDH">Updates to account for the shift from SF SVN to GitHub.</tei-change>
|
|
31
|
+
<tei-change data-origname="change" data-origatts="when who" when="2015-04-06" who="MDH">Added exhortation to include sufficient linebreaks in examples,
|
|
32
|
+
to avoid distorted page rendering in the Guidelines HTML output.</tei-change>
|
|
33
|
+
<tei-change data-origname="change" data-origatts="when who" when="2015-02-11" who="MDH">Added clarification about how to XInclude a new spec file.</tei-change>
|
|
34
|
+
<tei-change data-origname="change" data-origatts="when who" when="2013-12-22" who="KSH">Some clarifications, including not to use valDesc.</tei-change>
|
|
35
|
+
<tei-change data-origname="change" data-origatts="when who" when="2013-11-17" who="KSH">Made more explicit that you have to update @versionDate when editing the content of an element that it's located on.</tei-change>
|
|
36
|
+
<tei-change data-origname="change" data-origatts="when who" when="2013-06-24" who="KSH">When closing a ticket, add the URL of the revision number. Also replaced all "SVN" with "Subversion" when referring to the software.</tei-change>
|
|
37
|
+
<tei-change data-origname="change" data-origatts="when who" when="2013-06-20" who="KSH">Copyediting and clarified how to do citations per https://sourceforge.net/p/tei/bugs/527/ .</tei-change>
|
|
38
|
+
<tei-change data-origname="change" data-origatts="when who" when="2013-04-08" who="KSH">Full path to schema for validation</tei-change>
|
|
39
|
+
<tei-change data-origname="change" data-origatts="when who" when="2013-02-01" who="KSH">We should use egXML@source instead of egXML@corresp per Sebastian.</tei-change>
|
|
40
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-12-30" who="KSH">Clarified svn commit instructions.</tei-change>
|
|
41
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-12-28" who="KSH">Clarified what to include in a specList. Removed info that duplicates tcw24. Some light copyediting.</tei-change>
|
|
42
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-12-17" who="MDH">Revised instructions for creating a new element to take account of the switch to XInclude from entities.</tei-change>
|
|
43
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-09-13" who="MDH">Revised Schematron section based on feedback from KH.</tei-change>
|
|
44
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-09-06" who="MDH">Added a section on adding Schematron constraints.</tei-change>
|
|
45
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-08-09" who="DRS">Removed sections redundant with new TCW24 and redirected a link there.</tei-change>
|
|
46
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-05-15" who="KSH">Added instructions on when you can edit translations of specs.</tei-change>
|
|
47
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-05-14" who="KSH">Removed mention of P5/Source/Guidelines/en/style-guide.txt since this has been removed from SourceForge. Corrected @target to local copy of this document.</tei-change>
|
|
48
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-02-18" who="KSH">Created new section on good encoding practice, which includes info on @xml:id and @target and new note about using ptr instead of ref.</tei-change>
|
|
49
|
+
<tei-change data-origname="change" data-origatts="when who" when="2012-02-13" who="MDH">Removed "building a release" section and replaced with link to tcw22.</tei-change>
|
|
50
|
+
<tei-change data-origname="change" data-origatts="when who" when="2011-12-16" who="KSH">updated publicationStmt; added steps on updating latest download and creating news item in SourceForge</tei-change>
|
|
51
|
+
<tei-change data-origname="change" data-origatts="when" when="2011-12-16">correction by <tei-name data-origname="name">David Sewell</tei-name> per SR request</tei-change>
|
|
52
|
+
<tei-change data-origname="change" data-origatts="when" when="2011-02-19">started first draft</tei-change>
|
|
53
|
+
</tei-revisiondesc>
|
|
54
|
+
</tei-teiheader>
|
|
55
|
+
<tei-text data-origname="text">
|
|
56
|
+
<tei-body data-origname="body">
|
|
57
|
+
<tei-p data-origname="p">This document is intended to set out the way things are
|
|
58
|
+
currently managed in the
|
|
59
|
+
editing of the TEI Guidelines. General notes on the rationale
|
|
60
|
+
for this state -- <tei-emph data-origname="emph">why</tei-emph> it is the way it is -- may be added here
|
|
61
|
+
later. The intention is to provide information for Council
|
|
62
|
+
members wishing to contribute actively to the continued
|
|
63
|
+
development and maintenance of the text of the Guidelines. </tei-p>
|
|
64
|
+
<tei-div data-origname="div">
|
|
65
|
+
<tei-head data-origname="head">Organization of the Guidelines chapters</tei-head>
|
|
66
|
+
<tei-p data-origname="p">It cannot have escaped your notice that each chapter (almost) of the Guidelines defines a
|
|
67
|
+
distinct module. In theory at least, each chapter is organised in more or less the same
|
|
68
|
+
way: <tei-list data-origname="list">
|
|
69
|
+
<tei-item data-origname="item">it begins with a paragraph explaining what the module is for, and containing a lot
|
|
70
|
+
of links to the individual subsections it contains; </tei-item>
|
|
71
|
+
<tei-item data-origname="item">each subsection introduces a (small) group of elements, usually beginning with a
|
|
72
|
+
<tei-gi data-origname="gi">specList</tei-gi>, which will typically list all the elements discussed within a
|
|
73
|
+
given section, listed in whatever order makes sense for the context, but not necessary
|
|
74
|
+
all possible child elements for a given element; </tei-item>
|
|
75
|
+
<tei-item data-origname="item">each element is then introduced in turn, usually including an appropriate usage
|
|
76
|
+
example (on examples, see further <tei-ptr data-origname="ptr" data-origatts="target" target="#examples"></tei-ptr>); </tei-item>
|
|
77
|
+
<tei-item data-origname="item">a <tei-gi data-origname="gi">specGrp</tei-gi> for each group of elements defined may be given at the end of
|
|
78
|
+
each section; </tei-item>
|
|
79
|
+
<tei-item data-origname="item">a <tei-gi data-origname="gi">specGrp</tei-gi> for the whole module is given at the end of the chapter: it
|
|
80
|
+
includes the other specifications either directly (by means XIncludes) or
|
|
81
|
+
indirectly (by means of a <tei-gi data-origname="gi">specGrpRef</tei-gi> pointing to a preceding
|
|
82
|
+
<tei-gi data-origname="gi">specGrp</tei-gi>).</tei-item>
|
|
83
|
+
</tei-list></tei-p>
|
|
84
|
+
<tei-p data-origname="p">The only chapters not organised in this way are those which do not
|
|
85
|
+
introduce or define particular modules. </tei-p>
|
|
86
|
+
</tei-div>
|
|
87
|
+
<tei-div data-origname="div">
|
|
88
|
+
<tei-head data-origname="head">Organization of the specifications</tei-head>
|
|
89
|
+
<tei-p data-origname="p">Each element, class, and macro defined in the Guidelines is
|
|
90
|
+
declared within its own XML file,
|
|
91
|
+
containing an <tei-gi data-origname="gi">elementSpec</tei-gi>, <tei-gi data-origname="gi">classSpec</tei-gi>, or <tei-gi data-origname="gi">macroSpec</tei-gi> as
|
|
92
|
+
appropriate. These files are in the directory
|
|
93
|
+
<tei-ident data-origname="ident">Source/Specs</tei-ident>. For example, the file
|
|
94
|
+
<tei-ident data-origname="ident">Source/Specs/abbr.xml</tei-ident> contains the element spec for the <tei-gi data-origname="gi">abbr</tei-gi> element.
|
|
95
|
+
Note that the elements for the major components of the spec each have a <tei-att data-origname="att">versionDate</tei-att>.
|
|
96
|
+
<tei-emph data-origname="emph" data-origatts="rend" rend="bold">If editing the content of the element, you must remember to update the value of this
|
|
97
|
+
attribute</tei-emph> in order to allow for detection of translations (stored in the same file) that need
|
|
98
|
+
updating. As a general rule, don't update a translation for any language of which you are not
|
|
99
|
+
a native speaker. If you feel confident enough to adjust the translation, leave the
|
|
100
|
+
<tei-att data-origname="att">versionDate</tei-att> attribute unchanged on the translation in order to ensure the translation
|
|
101
|
+
will be reviewed eventually.</tei-p>
|
|
102
|
+
<tei-p data-origname="p">Each chapter of the Guidelines is stored in a file called
|
|
103
|
+
<tei-ident data-origname="ident">Source/Guidelines/xx/YY-name.xml</tei-ident> where xx is the language (currently only en or
|
|
104
|
+
fr), YY is the two letter identifier for each chapter (see <tei-ptr data-origname="ptr" data-origatts="target" target="#chaptercodes"></tei-ptr>)
|
|
105
|
+
and name is the name of the module being defined by that chapter. </tei-p>
|
|
106
|
+
<tei-p data-origname="p">The file <tei-ident data-origname="ident">Source/guidelines-xx.xml</tei-ident> (where xx is either en or fr) is the
|
|
107
|
+
<tei-socalled data-origname="soCalled">driver file</tei-socalled> for the whole shebang. It contains XInclude elements
|
|
108
|
+
for each of the chapters making up the Guidelines. </tei-p>
|
|
109
|
+
<tei-p data-origname="p">Hence, to add a new element (say <tei-gi data-origname="gi">saintName</tei-gi>) you
|
|
110
|
+
might proceed as follows: <tei-list data-origname="list" data-origatts="type" type="ordered">
|
|
111
|
+
<tei-item data-origname="item">Write a new file <tei-ident data-origname="ident">saintName.xml</tei-ident> containing an <tei-gi data-origname="gi">elementSpec</tei-gi>
|
|
112
|
+
for your new element and add it to the <tei-ident data-origname="ident">Specs</tei-ident> folder. Look at other specifications
|
|
113
|
+
to see which <tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/TD.html#TDcrystals">ODD elements</tei-ref>
|
|
114
|
+
to use. Note that we do not use <tei-gi data-origname="gi">valDesc</tei-gi> at this time, instead using only a <tei-gi data-origname="gi">datatype</tei-gi>.</tei-item>
|
|
115
|
+
<tei-item data-origname="item">Edit the source of the relevant chapter (presumably
|
|
116
|
+
<tei-ident data-origname="ident">ND-namesdates.xml</tei-ident> in this example) to include a documentation of the element. Use a
|
|
117
|
+
<tei-gi data-origname="gi">specList</tei-gi> to reference the description from your new spec within the body of
|
|
118
|
+
the text, like this:
|
|
119
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML">
|
|
120
|
+
<teieg-p data-teiname="p">This module also defines the following canonical element: <teieg-speclist data-teiname="specList">
|
|
121
|
+
<teieg-specdesc data-teiname="specDesc" key="saintName"></teieg-specdesc>
|
|
122
|
+
</teieg-speclist></teieg-p>
|
|
123
|
+
</teieg-egxml>
|
|
124
|
+
|
|
125
|
+
and follow up with some discussion of usage.
|
|
126
|
+
</tei-item>
|
|
127
|
+
<!-- This item added by MDH 2015-02-11. -->
|
|
128
|
+
<tei-item data-origname="item">Also in the relevant chapter, make sure you include an XInclude instruction to bring the specification
|
|
129
|
+
file for your element into the Guidelines source. Normally you would add it to an existing <tei-gi data-origname="gi">specGrp</tei-gi>
|
|
130
|
+
element somewhere in the chapter source which already contains similar links:
|
|
131
|
+
<tei-eg data-origname="eg">
|
|
132
|
+
<specGrp xml:id="DNDPER" n="Personal and organizational names">
|
|
133
|
+
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/orgName.xml"/>
|
|
134
|
+
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/saintName.xml"/>
|
|
135
|
+
[...]
|
|
136
|
+
</specGrp>
|
|
137
|
+
</tei-eg>
|
|
138
|
+
|
|
139
|
+
</tei-item>
|
|
140
|
+
</tei-list>
|
|
141
|
+
</tei-p>
|
|
142
|
+
</tei-div>
|
|
143
|
+
|
|
144
|
+
<!-- This section added by MDH 2013-04-26 as part of work on https://sourceforge.net/p/tei/bugs/512/.
|
|
145
|
+
Extra clarification added by MDH 2016-07-08. -->
|
|
146
|
+
<tei-div data-origname="div">
|
|
147
|
+
<tei-head data-origname="head">Processing Instructions</tei-head>
|
|
148
|
+
<tei-p data-origname="p">In some places in the Guidelines source code, you will notice processing instructions which look like this:
|
|
149
|
+
|
|
150
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML">
|
|
151
|
+
<?insert totalElements?>
|
|
152
|
+
</teieg-egxml>
|
|
153
|
+
|
|
154
|
+
These processing instructions are replaced during the Guidelines build process by generated content. (That processing
|
|
155
|
+
takes place in the XSL module P5/Utilities/expand.xsl.) In the
|
|
156
|
+
case of the example above, the total number of elements defined in the current version of the Guidelines is
|
|
157
|
+
calculated and inserted. This is a list of the processing instructions currently in use, and what they are replaced
|
|
158
|
+
by:
|
|
159
|
+
|
|
160
|
+
<tei-list data-origname="list" data-origatts="type" type="gloss">
|
|
161
|
+
<tei-label data-origname="label"><?insert tab-content-models?></tei-label>
|
|
162
|
+
<tei-item data-origname="item">Inserts a generated table of content models into the ST chapter (not likely to be used elsewhere)</tei-item>
|
|
163
|
+
<tei-label data-origname="label"><?insert totalElements?></tei-label>
|
|
164
|
+
<tei-item data-origname="item">Inserts a count of the total number of elements defined in the current version</tei-item>
|
|
165
|
+
<tei-label data-origname="label"><?insert version?></tei-label>
|
|
166
|
+
<tei-item data-origname="item">Inserts the current version number of the TEI release</tei-item>
|
|
167
|
+
</tei-list>
|
|
168
|
+
|
|
169
|
+
If you are writing a Guidelines section that can use one of these variables, feel free to insert the appropriate
|
|
170
|
+
processing instruction. If you think of other content that could be generated in this way, raise an issue on GitHub so that it can be implemented.
|
|
171
|
+
</tei-p>
|
|
172
|
+
</tei-div>
|
|
173
|
+
|
|
174
|
+
<tei-div data-origname="div">
|
|
175
|
+
<tei-head data-origname="head">Style Notes</tei-head>
|
|
176
|
+
<tei-div data-origname="div">
|
|
177
|
+
<tei-head data-origname="head">General</tei-head>
|
|
178
|
+
<tei-p data-origname="p">See the <tei-ref data-origname="ref" data-origatts="target" target="https://teic.github.io/TCW/tcw24.html">Style
|
|
179
|
+
Guide for Editing the TEI Guidelines</tei-ref>,
|
|
180
|
+
which attempts to state preferred practice on vexed issues
|
|
181
|
+
issues about spelling, punctuation, etc. The goal of these rules is to avoid
|
|
182
|
+
inconsistency, and also (wherever possible) to avoid producing text which is markedly
|
|
183
|
+
either British or American English. </tei-p>
|
|
184
|
+
<tei-p data-origname="p"></tei-p>
|
|
185
|
+
</tei-div>
|
|
186
|
+
<tei-div id="examples" data-origname="div" data-origatts="id" xml:id="examples">
|
|
187
|
+
<tei-head data-origname="head">Examples</tei-head>
|
|
188
|
+
<tei-p data-origname="p">The purpose of an example is to illustrate a specific element or feature. Do not
|
|
189
|
+
include irrelevant encoding which does not contribute to this primary goal. If such
|
|
190
|
+
encoding is unavoidable (eg to make your example valid), then it must be explained in
|
|
191
|
+
the supporting text. You may provide supporting explanation for an example in one of two ways:
|
|
192
|
+
in a <tei-gi data-origname="gi">p</tei-gi> element within the <tei-gi data-origname="gi">exemplum</tei-gi>, or in a <tei-gi data-origname="gi">remarks</tei-gi> element.
|
|
193
|
+
A <tei-gi data-origname="gi">p</tei-gi> element within an <tei-gi data-origname="gi">exemplum</tei-gi> should only be used for an explanation specific to that particular example.
|
|
194
|
+
A <tei-gi data-origname="gi">remarks</tei-gi> element should provide explanation for the usage of an element or attribute and need not be tied to a specific example,
|
|
195
|
+
though it may refer to one. Be careful when writing a supporting explanation not to refer to an example as
|
|
196
|
+
<tei-q data-origname="q">above</tei-q> or <tei-q data-origname="q">below</tei-q> the explanation, or to indicate the <tei-q data-origname="q">first</tei-q> or <tei-q data-origname="q">second</tei-q> example in a series since
|
|
197
|
+
the rendering of the Guidelines could change and examples could change order or position as new ones are added.</tei-p>
|
|
198
|
+
<tei-p data-origname="p">Wherever possible, choose your examples from real documents and provide bibliographic
|
|
199
|
+
citations for them, either:
|
|
200
|
+
<tei-list data-origname="list">
|
|
201
|
+
<tei-item data-origname="item">in a <tei-gi data-origname="gi">note</tei-gi> element, with a <tei-att data-origname="att">place</tei-att> whose value is <tei-val data-origname="val">bottom</tei-val> or
|
|
202
|
+
<tei-val data-origname="val">foot</tei-val>, following the <tei-gi data-origname="gi">egXML</tei-gi> (if the citation is only a URL in a
|
|
203
|
+
<tei-gi data-origname="gi">ptr</tei-gi>)</tei-item>
|
|
204
|
+
<tei-item data-origname="item">in a full bibliographic citation (with or without a URL in <tei-gi data-origname="gi">ptr</tei-gi>) in
|
|
205
|
+
the file <tei-ident data-origname="ident">BIB-Bibliography.xml</tei-ident></tei-item>
|
|
206
|
+
</tei-list>
|
|
207
|
+
Use the <tei-att data-origname="att">source</tei-att> attribute on the <tei-gi data-origname="gi">egXML</tei-gi> element to link an example to its source. Note
|
|
208
|
+
that the <tei-att data-origname="att">xml:lang</tei-att> attribute is mandatory on <tei-gi data-origname="gi">exemplum</tei-gi>: this is to
|
|
209
|
+
ensure that the ODD processor knows which examples to choose in a given context.</tei-p>
|
|
210
|
+
<tei-p data-origname="p">All examples should be valid against a modified TEI schema in which any element can act
|
|
211
|
+
as a root element; this validity is checked during the build process. </tei-p>
|
|
212
|
+
<tei-p data-origname="p">When you have added or edited examples, always check in the following Jenkins build
|
|
213
|
+
that they are displaying correctly. In particular, note that if your examples include
|
|
214
|
+
long lines without linebreaks, the result can be a horizontally-scrolling page and a
|
|
215
|
+
broken table layout in the reference page. If you see this in the output, you can fix it
|
|
216
|
+
by adding hard-coded linebreaks at suitable points in the example code.</tei-p>
|
|
217
|
+
</tei-div>
|
|
218
|
+
|
|
219
|
+
<tei-div id="encoding" data-origname="div" data-origatts="id" xml:id="encoding">
|
|
220
|
+
<tei-head data-origname="head">Good encoding practice</tei-head>
|
|
221
|
+
<tei-p data-origname="p">Good encoding practice will ensure not only valid but
|
|
222
|
+
also highly functional Guidelines.</tei-p>
|
|
223
|
+
<tei-p data-origname="p">When referencing figures and to other sections of the
|
|
224
|
+
Guidelines, use <tei-gi data-origname="gi">ptr</tei-gi>, not <tei-gi data-origname="gi">ref</tei-gi>, to ensure
|
|
225
|
+
that the title and number of the referenced item is
|
|
226
|
+
automatically inserted when the Guidelines are compiled.</tei-p>
|
|
227
|
+
<tei-p data-origname="p">The build process validates cross-references.
|
|
228
|
+
Since the Guidelines is compiled into a single XML document
|
|
229
|
+
at build time, IDs must be unique across the text and the
|
|
230
|
+
examples. Consequently, any <tei-att data-origname="att">xml:id</tei-att> attribute
|
|
231
|
+
values appearing in your examples must be unique within the
|
|
232
|
+
text of the whole of the Guidelines. Furthermore, any
|
|
233
|
+
<tei-att data-origname="att">target</tei-att> (etc.) values which do not point to
|
|
234
|
+
anything in the source will be flagged with a warning during
|
|
235
|
+
the build process. </tei-p>
|
|
236
|
+
</tei-div>
|
|
237
|
+
</tei-div>
|
|
238
|
+
<tei-div data-origname="div">
|
|
239
|
+
<tei-head data-origname="head">Making a change to the Guidelines</tei-head>
|
|
240
|
+
<!-- Substantially edited by MDH 2015-10-03 for shift to GitHub. -->
|
|
241
|
+
<tei-p data-origname="p">Most changes to the Guidelines are the result of a bug or feature request
|
|
242
|
+
ticket on GitHub. Once a ticket is assigned to you, and you're sure there
|
|
243
|
+
is agreement to proceed with the change, follow the steps below.</tei-p>
|
|
244
|
+
|
|
245
|
+
<tei-list data-origname="list">
|
|
246
|
+
<tei-item data-origname="item">If you don't have a local clone of the git repo, go to the <tei-ref data-origname="ref" data-origatts="target" target="https://github.com/TEIC/TEI">GitHub site</tei-ref> and clone the repository following the instructions there. It's usually something like <tei-code data-origname="code">git clone https://github.com/TEIC/TEI.git TEI</tei-code> </tei-item>
|
|
247
|
+
<tei-item data-origname="item">If you have already checked out a copy, make sure to update it (<tei-code data-origname="code">git pull</tei-code>) <tei-emph data-origname="emph">before</tei-emph>
|
|
248
|
+
you make any changes in it.</tei-item>
|
|
249
|
+
<tei-item data-origname="item">Make sure you are on the <tei-code data-origname="code">dev</tei-code> branch (we do not make direct changes to the master branch): <tei-code data-origname="code">git checkout dev</tei-code></tei-item>
|
|
250
|
+
<tei-item data-origname="item">Edit the appropriate file(s) to make your changes, or if the change requires it, create a new file. Make sure your source is still valid. The TEI source files should all
|
|
251
|
+
contain xml-model processing instructions linking them to the latest version
|
|
252
|
+
of the NVDL file used for validation of the P5 source.</tei-item>
|
|
253
|
+
<tei-item data-origname="item">If you have a locally installed P5 build environment, make sure you can still build,
|
|
254
|
+
and that the examples are still valid. You can set up a Docker-based build environment
|
|
255
|
+
by following the instructions in <tei-ptr data-origname="ptr" data-origatts="target" target="http://teic.github.io/TCW/testing_and_building.html"></tei-ptr>. If you do not have a build
|
|
256
|
+
environment nor the means to set one up, just use git to push your updated version to
|
|
257
|
+
GitHub and wait for our two <tei-ident data-origname="ident">Jenkins</tei-ident> Continuous Integration servers (<tei-ptr data-origname="ptr" data-origatts="target" target="http://jenkins.tei-c.org/"></tei-ptr> and <tei-ptr data-origname="ptr" data-origatts="target" target="http://jenkins2.tei-c.org/"></tei-ptr>) to assess your work.</tei-item>
|
|
258
|
+
<tei-item data-origname="item">Check in your changes:
|
|
259
|
+
<tei-list data-origname="list">
|
|
260
|
+
<tei-item data-origname="item">If the file is new, add it to the git repository: <tei-code data-origname="code">git add filename.xml</tei-code></tei-item>
|
|
261
|
+
</tei-list>
|
|
262
|
+
</tei-item>
|
|
263
|
+
<tei-item data-origname="item">Commit your changes: <tei-code data-origname="code">git commit -m "Your commit message" filename.xml</tei-code> <tei-emph data-origname="emph">Be sure to add a detailed commit message which includes a link to the git issue ticket which prompted the change</tei-emph>.</tei-item>
|
|
264
|
+
<tei-item data-origname="item">Push the change to the git repository: <tei-code data-origname="code">git push origin dev</tei-code></tei-item>
|
|
265
|
+
<tei-item data-origname="item">Make a note of the revision hash when git receives your change.</tei-item>
|
|
266
|
+
<tei-item data-origname="item">Assuming the change was successful (see below), add a comment to the GitHub issue ticket which includes the hash of the revision. You may also close the ticket if it is complete.</tei-item>
|
|
267
|
+
</tei-list>
|
|
268
|
+
<tei-p data-origname="p">Error messages may appear at any stage. Please do not leave the source in an invalid
|
|
269
|
+
state (it makes life unnecessarily difficult for others). If you cannot immediately fix a
|
|
270
|
+
validity error, revert your change while you think about it.</tei-p>
|
|
271
|
+
<tei-p data-origname="p">Most minor changes, such as edits to explanatory text, can be committed directly to the dev branch. Some edits are more complex, and particularly when these involve multiple files as in adding new elements or changing class specs, it is best to open a new temporary branch to do this work. If it takes some time to complete work on the new branch, you should probably keep the temporary branch up to date with the dev branch with <tei-code data-origname="code">git rebase</tei-code>, since this sets the branch work ahead of the latest commits to dev. (It is also a good idea to ensure that other Council members are not committing edits on the dev branch to the same files that you are working on in the new branch.) For more details on keeping branches up to date, see the <tei-ref data-origname="ref" data-origatts="target" target="https://www.atlassian.com/git/tutorials/merging-vs-rebasing">Atalassian tutorial on merging vs. rebasing</tei-ref>. When your work on the temporary branch is ready for review, push your latest changes and open a pull request. (You can do this by opening the web browser view of the remote TEI GitHub repo, selecting the Pull Requests tab and “New Pull Request”, and comparing your branch to the base dev branch.) Once you have created the pull request, another member of Council should approve it. You can assign specific Council members to this task, or assign the entire Council as a team with <tei-code data-origname="code">@TEIC/tei-technical-council</tei-code>. Bear in mind that our Jenkins servers only build the dev branch, so you cannot depend on them to test-build your working branch. If you need regular test-builds for your branch, or you would like to be able to share the results of your branch build with others while you're working on it, you can ask one of the Jenkins maintainers to set up a temporary build job for your branch. A pull request should only be approved when its contents pass the Jenkins server tests. The Council member who approves a pull request should delete the temporary branch once its content has been merged into dev.</tei-p>
|
|
272
|
+
|
|
273
|
+
<tei-p data-origname="p">The Jenkins servers monitor the Git repository, and when they detect a change, they check it out and commence building several targets, just as you would build them on your local machine. There are a couple of advantages to letting the Jenkins servers check your build for you:</tei-p>
|
|
274
|
+
|
|
275
|
+
<tei-list data-origname="list">
|
|
276
|
+
<tei-item data-origname="item">You don't have to have all the various packages and other software required for a build installed on your system. This means you can make a quick fix to the Guidelines on any computer you happen to be using, without installing a lot of extra software.</tei-item>
|
|
277
|
+
<tei-item data-origname="item">The required packages on the Jenkins servers tend to be updated regularly, and we're watching them to make sure they work properly.</tei-item>
|
|
278
|
+
<tei-item data-origname="item">Jenkins attempts to let you know by email if there's a problem, and provides useful debugging tools.</tei-item>
|
|
279
|
+
</tei-list>
|
|
280
|
+
|
|
281
|
+
<tei-p data-origname="p">If you submit a change, and later get an email from one of the Jenkins servers telling you that the build failed, it will provide a link to the build information on the server. Here's what to do:</tei-p>
|
|
282
|
+
|
|
283
|
+
<tei-list data-origname="list">
|
|
284
|
+
<tei-item data-origname="item">First, check that the build is broken on both Jenkins servers. If it's only broken on one of them, it may have been caused by a lag in updates to packages on that server. </tei-item>
|
|
285
|
+
<tei-item data-origname="item">If both servers have completed a build since your commit, and both are showing an error, then you need to check where the error is occurring. On the page for that build on the Jenkins server site, click on <tei-q data-origname="q">Parsed Console Output</tei-q> on the left menu. You'll see links to <tei-q data-origname="q">Errors</tei-q> and <tei-q data-origname="q">Warnings</tei-q>; these will show you the exact point in the build script where the errors or warnings occurred. This may give you a useful clue to the cause of the failure.</tei-item>
|
|
286
|
+
<tei-item data-origname="item">If you still can't figure out the problem, email the Council list with a link to the build information, and someone will be able to help.</tei-item>
|
|
287
|
+
<tei-item data-origname="item">Once you know what the problem is, fix it by editing the source again and committing the change to the git repository. Jenkins will then do its stuff, and you'll know whether your fix worked as expected.</tei-item>
|
|
288
|
+
</tei-list>
|
|
289
|
+
|
|
290
|
+
<tei-p data-origname="p">Error messages appearing during the <tei-ident data-origname="ident">make test</tei-ident> phase (the <tei-q data-origname="q">TEIP5-Test</tei-q> job on Jenkins) usually indicate that
|
|
291
|
+
your changes are in conflict with the Birnbaum Doctrine, which decrees that changes in the
|
|
292
|
+
Guideline schemas should not invalidate existing documents. You may wish to discuss the
|
|
293
|
+
specific issue with other Council members.</tei-p>
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
<!-- The following div added by MDH 2013-11-10 per https://sourceforge.net/p/tei/bugs/612/. -->
|
|
297
|
+
<tei-div data-origname="div">
|
|
298
|
+
<tei-head data-origname="head">Images</tei-head>
|
|
299
|
+
|
|
300
|
+
<tei-p data-origname="p">If you use an image in your Guidelines change, you will need to add it to the git repository
|
|
301
|
+
in the <tei-ident data-origname="ident">P5/Images</tei-ident> directory. If you have asked for and received permission
|
|
302
|
+
from a rights-holder to use the image, include all of the relevant correspondence in a zip
|
|
303
|
+
file named the same as the image file (so for an image <tei-ident data-origname="ident">fred.png</tei-ident>, include
|
|
304
|
+
permission documents in a file called <tei-ident data-origname="ident">fred.zip</tei-ident>).</tei-p>
|
|
305
|
+
</tei-div>
|
|
306
|
+
|
|
307
|
+
<!-- This div added by MDH 2018-09-16 following work
|
|
308
|
+
on ticket #1657.
|
|
309
|
+
-->
|
|
310
|
+
<tei-div id="appendices" data-origname="div" data-origatts="id" xml:id="appendices">
|
|
311
|
+
<tei-head data-origname="head">Adding or Editing an Appendix</tei-head>
|
|
312
|
+
|
|
313
|
+
<tei-p data-origname="p">The Appendices to the <tei-title data-origname="title" data-origatts="level" level="m">TEI Guidelines</tei-title> mostly constitute lists of features (elements, attributes, classes etc.) which have been automatically harvested from the Guidelines compiled source (<tei-ident data-origname="ident">p5.xml</tei-ident> or <tei-ident data-origname="ident">p5subset.xml</tei-ident>) during the build process. When adding a new appendix of this type, you need to:
|
|
314
|
+
|
|
315
|
+
<tei-list data-origname="list" data-origatts="rend" rend="numbered">
|
|
316
|
+
<tei-item data-origname="item">Create a new <tei-ident data-origname="ident">APPENDIXTHING.xml</tei-ident> file in the <tei-ident data-origname="ident">TEI/P5/Source/Guidelines/en/</tei-ident> folder. Model this on the already-existing files for other appendices. The basic pattern is to provide a very short introduction to the list you're creating (see below). The convention is to name this file with an all-caps name followed by lower-case <tei-ident data-origname="ident">.xml</tei-ident>.</tei-item>
|
|
317
|
+
|
|
318
|
+
<tei-item data-origname="item">Add a line to <tei-ident data-origname="ident">TEI/P5/Source/guidelines-en.xml</tei-ident> (right near the end of the file) to XInclude your file in the <tei-title data-origname="title" data-origatts="level" level="m">Guidelines</tei-title>. Again, follow the examples already there. Put your new appendix in the sequence in a location that makes sense in relation to the other appendices.</tei-item>
|
|
319
|
+
|
|
320
|
+
<tei-item data-origname="item">If your appendix listing is to be created automatically, edit the appropriate file in the Stylesheets repository (most likely <tei-ident data-origname="ident">Stylesheets/common/common_tagdocs.xsl</tei-ident>) to enable it to generate the list or table (see below).</tei-item>
|
|
321
|
+
|
|
322
|
+
<tei-item data-origname="item">If your auto-generated appendix content uses headings that should be translated for other language versions of the Guidelines, add the appropriate language entries to <tei-ident data-origname="ident">Stylesheets/i18n.xml</tei-ident> (if they're not already there).</tei-item>
|
|
323
|
+
</tei-list>
|
|
324
|
+
</tei-p>
|
|
325
|
+
|
|
326
|
+
<tei-p data-origname="p">Auto-generated appendix listings will require two things: a TEI <tei-gi data-origname="gi">divGen</tei-gi> element which acts as a trigger to cause the list to be generated, and a Stylesheets template which processes the <tei-gi data-origname="gi">divGen</tei-gi> to create the output. For example, the list of deprecations consists of this <tei-ident data-origname="ident">DEPRECATIONS.xml</tei-ident> file:
|
|
327
|
+
|
|
328
|
+
|
|
329
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML">
|
|
330
|
+
<teieg-div id="DEPRECATIONS" data-teiname="div" type="div1" xml:id="DEPRECATIONS">
|
|
331
|
+
<teieg-head data-teiname="head">Deprecations</teieg-head>
|
|
332
|
+
<teieg-div data-teiname="div">
|
|
333
|
+
<teieg-head data-teiname="head">About the Deprecation Appendix</teieg-head>
|
|
334
|
+
<teieg-p data-teiname="p">This appendix gives you a list of all items (elements,
|
|
335
|
+
attributes, attribute values, datatypes etc.) which are deprecated
|
|
336
|
+
in this revision of the TEI Guidelines (revision <?insert
|
|
337
|
+
revision?> of TEI P5 <?insert version?>).</teieg-p>
|
|
338
|
+
</teieg-div>
|
|
339
|
+
<teieg-divgen data-teiname="divGen" type="deprecationcat"></teieg-divgen>
|
|
340
|
+
</teieg-div>
|
|
341
|
+
</teieg-egxml>
|
|
342
|
+
|
|
343
|
+
Note that there are two kinds of auto-generated content here: first, the two processing instructions
|
|
344
|
+
<tei-code data-origname="code"><?insert revision?></tei-code> and
|
|
345
|
+
<tei-code data-origname="code"><?insert version?></tei-code>, which are self-explanatory and can simply be used, and
|
|
346
|
+
<tei-code data-origname="code"><divGen type="deprecationcat"/></tei-code>, which was created specifically for this appendix file, and for which processing had to be explicitly written.
|
|
347
|
+
|
|
348
|
+
If you now look at <tei-ident data-origname="ident">Stylesheets/common/common_tagdocs.xsl</tei-ident>, you'll find this template:
|
|
349
|
+
|
|
350
|
+
|
|
351
|
+
<tei-eg data-origname="eg">
|
|
352
|
+
<xsl:template match="tei:divGen[@type = 'deprecationcat']">
|
|
353
|
+
<xsl:element namespace="{$outputNS}" name="{$tableName}">
|
|
354
|
+
<xsl:attribute name="{$rendName}">
|
|
355
|
+
<xsl:text>deprecationcat</xsl:text>
|
|
356
|
+
</xsl:attribute>
|
|
357
|
+
<!-- .. -->
|
|
358
|
+
</xsl:element>
|
|
359
|
+
</xsl:template>
|
|
360
|
+
</tei-eg>
|
|
361
|
+
|
|
362
|
+
This template creates a table in whatever the target output format is, listing the deprecations. Note that the table headings are created like this:
|
|
363
|
+
|
|
364
|
+
|
|
365
|
+
<tei-eg data-origname="eg">
|
|
366
|
+
<xsl:element namespace="{$outputNS}" name="{$cellName}">
|
|
367
|
+
<xsl:element namespace="{$outputNS}" name="{$hiName}">
|
|
368
|
+
<xsl:attribute name="{$rendName}">
|
|
369
|
+
<xsl:text>label</xsl:text>
|
|
370
|
+
</xsl:attribute>
|
|
371
|
+
<xsl:attribute name="{$langAttributeName}">
|
|
372
|
+
<xsl:value-of select="$documentationLanguage"/>
|
|
373
|
+
</xsl:attribute>
|
|
374
|
+
<xsl:sequence select="tei:i18n('Identifier')"/>
|
|
375
|
+
</xsl:element>
|
|
376
|
+
</xsl:element>
|
|
377
|
+
</tei-eg>
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
where the keyword <tei-val data-origname="val">Identifier</tei-val> is used to look up the appropriate language translation in the <tei-ident data-origname="ident">Stylesheets/i18n.xml</tei-ident> file. If those items already exist in the file, you can simply use them, but if you are creating headings which do not yet have entries, you will need to add them to <tei-ident data-origname="ident">Stylesheets/i18n.xml</tei-ident> like this:
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML">
|
|
384
|
+
<teieg-entry data-teiname="entry">
|
|
385
|
+
<teieg-key data-teiname="key">Identifier</teieg-key>
|
|
386
|
+
<teieg-text lang="en" data-teiname="text" xml:lang="en" lang3="eng">Identifier</teieg-text>
|
|
387
|
+
</teieg-entry>
|
|
388
|
+
</teieg-egxml>
|
|
389
|
+
|
|
390
|
+
and if you are competent to add the equivalent translations in any of the <tei-title data-origname="title" data-origatts="level" level="m">Guidelines</tei-title> languages, you can add them alongside the English version:
|
|
391
|
+
|
|
392
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML">
|
|
393
|
+
<teieg-entry data-teiname="entry">
|
|
394
|
+
<teieg-key data-teiname="key">Description</teieg-key>
|
|
395
|
+
<teieg-text lang="en" data-teiname="text" xml:lang="en" lang3="eng">Description</teieg-text>
|
|
396
|
+
<teieg-text lang="de" data-teiname="text" xml:lang="de" lang3="deu">Beschreibung</teieg-text>
|
|
397
|
+
<teieg-text lang="fr" data-teiname="text" xml:lang="fr" lang3="fra">Description</teieg-text>
|
|
398
|
+
<teieg-text lang="it" data-teiname="text" xml:lang="it" lang3="ita">Descrizione</teieg-text>
|
|
399
|
+
</teieg-entry>
|
|
400
|
+
</teieg-egxml>
|
|
401
|
+
Only when all these pieces are in place can the new appendix function correctly. It would normally be appropriate to do work on this scale in a branch of the repo, but this is a little complicated by the fact that you need to edit two repositories separately. It is fine to make the changes in the TEI repository first, resulting in an appendix page that simply lacks its listing, then do the Stylesheets changes to make the listing.</tei-p>
|
|
402
|
+
|
|
403
|
+
<tei-p data-origname="p">Of course, a simple <tei-socalled data-origname="soCalled">manual</tei-socalled> appendix consisting of some explanatory prose can be created simply by adding the <tei-ident data-origname="ident">APPENDIXTHING.xml</tei-ident> file and XIncluding it in <tei-ident data-origname="ident">guidelines-en.xml</tei-ident>, with no Stylesheets changes required.</tei-p>
|
|
404
|
+
|
|
405
|
+
</tei-div>
|
|
406
|
+
|
|
407
|
+
</tei-div>
|
|
408
|
+
|
|
409
|
+
|
|
410
|
+
<tei-div id="schematron" data-origname="div" data-origatts="id" xml:id="schematron">
|
|
411
|
+
|
|
412
|
+
<tei-head data-origname="head">Adding Schematron constraints to specifications</tei-head>
|
|
413
|
+
|
|
414
|
+
<tei-p data-origname="p">The TEI ODD system is primarily concerned with generating schemas in the form of RelaxNG or XML Schema.
|
|
415
|
+
However, there are often circumstances in which you want to apply constraints to elements and attributes which cannot easily be captured by
|
|
416
|
+
normal XML schemas. For instance, you might want to apply a co-occurrence constraint on some attributes. The <tei-att data-origname="att">targetLang</tei-att> attribute
|
|
417
|
+
is a good example. <tei-att data-origname="att">targetLang</tei-att> is an optional attribute which “specifies the language of the content to be found
|
|
418
|
+
at the destination referenced by <tei-att data-origname="att">target</tei-att>, using a <tei-socalled data-origname="soCalled">language tag</tei-socalled> generated according to
|
|
419
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.rfc-editor.org/rfc/bcp/bcp47.txt">BCP 47</tei-ref>.” Obviously, there is no point in using <tei-att data-origname="att">targetLang</tei-att>
|
|
420
|
+
if you're not also using <tei-att data-origname="att">target</tei-att>. However, many such co-occurrence constraints are difficult to express
|
|
421
|
+
in RelaxNG schemas, and may not survive conversion to other schema formats such as XML Schema or DTD.</tei-p>
|
|
422
|
+
|
|
423
|
+
<tei-p data-origname="p">For this reason, we often use ISO Schematron to express constraints like this. If you look in att.pointing.xml, where the <tei-att data-origname="att">targetLang</tei-att>
|
|
424
|
+
attribute is defined, you'll find this constraint, inside the <tei-gi data-origname="gi">attDef</tei-gi> for <tei-att data-origname="att">targetLang</tei-att>:</tei-p>
|
|
425
|
+
|
|
426
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML">
|
|
427
|
+
<teieg-constraintspec data-teiname="constraintSpec" ident="targetLang" scheme="isoschematron">
|
|
428
|
+
<teieg-constraint data-teiname="constraint">
|
|
429
|
+
<sch:rule xmlns:sch="http://purl.oclc.org/dsdl/schematron" context="tei:*[not(self::tei:schemaSpec)][@targetLang]" role="error">
|
|
430
|
+
<sch:assert test="count(@target)">@targetLang can only be used if
|
|
431
|
+
@target is specified.</sch:assert>
|
|
432
|
+
</sch:rule>
|
|
433
|
+
</teieg-constraint>
|
|
434
|
+
</teieg-constraintspec>
|
|
435
|
+
</teieg-egxml>
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
<tei-p data-origname="p">This Schematron rule is an assertion that if <tei-att data-origname="att">targetLang</tei-att> is used, <tei-att data-origname="att">target</tei-att> should also be present. <tei-gi data-origname="gi">constraintSpec</tei-gi>
|
|
439
|
+
has an attribute <tei-att data-origname="att">scheme</tei-att> (normally set to <tei-val data-origname="val">isoschematron</tei-val>). Inside <tei-gi data-origname="gi">constraintSpec</tei-gi>, <tei-gi data-origname="gi">constraints</tei-gi>s hold elements in the Schematron namespace. The Schematron <tei-gi data-origname="gi">rule</tei-gi> element establishes the TEI node to be tested with its <tei-att data-origname="att">context</tei-att> attribute. The <tei-gi data-origname="gi">rule</tei-gi> holds one or more elements, either <tei-gi data-origname="gi">assert</tei-gi> or <tei-gi data-origname="gi">report</tei-gi> that define conditions to be checked in a <tei-att data-origname="att">test</tei-att> attribute. Here we see an <tei-gi data-origname="gi">assert</tei-gi> element,
|
|
440
|
+
which has <tei-att data-origname="att">test</tei-att> attributes. The <tei-att data-origname="att">test</tei-att> attribute value is always an XPath expression; if the XPath tests false, the assertion will be triggered, and its
|
|
441
|
+
contents will appear on the console when you build or validate. There is also a <tei-gi data-origname="gi">report</tei-gi> element which is similar, but which triggers when true rather than when false,
|
|
442
|
+
so you can check both positive and negative conditions. In Roma, you can also generate a Schematron schema which you can also use to test your document against.
|
|
443
|
+
This document is essentially a compilation in Schematron of all the TEI constraints. The operation of checking a document with Schematron is independent of any other validation
|
|
444
|
+
processes that take place using other schemas. Notice, finally, the <tei-att data-origname="att">role</tei-att> attribute, set in our example on the <tei-gi data-origname="gi">rule</tei-gi> element. This attribute defines a level of severity for the test if its test passes with a Boolean true result in a <tei-gi data-origname="gi">report</tei-gi>, or if the test fails with a Boolean false result in a <tei-gi data-origname="gi">assert</tei-gi>. Values for <tei-att data-origname="att">role</tei-att> basically define three levels of severity, for which we use standard Schematron values: with "fatal" and "error" as the most extreme values, "warning" as a gentle caution, and "info" to provide neutral information. When no <tei-att data-origname="att">role</tei-att> attribute is set, the default severity in Schematron is "error". The <tei-att data-origname="att">role</tei-att> attribute can be applied either to the Schematron <tei-gi data-origname="gi">rule</tei-gi> element or to its <tei-gi data-origname="gi">assert</tei-gi> and <tei-gi data-origname="gi">report</tei-gi> children, which can have differing levels of severity. For a full introduction to Schematron, see the <tei-ref data-origname="ref" data-origatts="target" target="http://www.schematron.com">Schematron website</tei-ref>.</tei-p>
|
|
445
|
+
|
|
446
|
+
<tei-p data-origname="p"><tei-gi data-origname="gi">constraintSpec</tei-gi> can appear as a child of <tei-gi data-origname="gi">attDef</tei-gi>, <tei-gi data-origname="gi">classSpec</tei-gi>, <tei-gi data-origname="gi">elementSpec</tei-gi>, <tei-gi data-origname="gi">macroSpec</tei-gi>, and <tei-gi data-origname="gi">schemaSpec</tei-gi>.
|
|
447
|
+
We'll go through the process of adding a constraint like the one above. The constraint we're going to add relates to dating elements (<tei-gi data-origname="gi">date</tei-gi>, <tei-gi data-origname="gi">birth</tei-gi> etc.) and
|
|
448
|
+
the <tei-att data-origname="att">calendar</tei-att> attribute. <tei-att data-origname="att">calendar</tei-att> <tei-q data-origname="q">indicates the system or calendar to which the date represented by the content of this element belongs.</tei-q> In other
|
|
449
|
+
words, <tei-att data-origname="att">calendar</tei-att> should only be used if the dating element has textual content. This makes sense (assuming that <tei-att data-origname="att">calendar</tei-att> points at a valid <tei-gi data-origname="gi">calendar</tei-gi> element):
|
|
450
|
+
|
|
451
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML" valid="true">
|
|
452
|
+
<teieg-date data-teiname="date" calendar="#julian">January, 1622</teieg-date>
|
|
453
|
+
</teieg-egxml>
|
|
454
|
+
|
|
455
|
+
|
|
456
|
+
whereas this is not:
|
|
457
|
+
|
|
458
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML" valid="false">
|
|
459
|
+
<teieg-date data-teiname="date" when="1622" calendar="#julian"></teieg-date>
|
|
460
|
+
</teieg-egxml>
|
|
461
|
+
|
|
462
|
+
|
|
463
|
+
because the <tei-gi data-origname="gi">date</tei-gi> element has no textual content to which the <tei-att data-origname="att">calendar</tei-att> attribute could apply. We're going to express this in the form of a Schematron
|
|
464
|
+
constraint, along the lines of the one we've examined above. First, we open the att.datable.xml file, and find the <tei-gi data-origname="gi">attDef</tei-gi> element which defines <tei-att data-origname="att">calendar</tei-att>.
|
|
465
|
+
We can add the <tei-gi data-origname="gi">constraintSpec</tei-gi> element immediately after the <tei-gi data-origname="gi">datatype</tei-gi> element, like this:
|
|
466
|
+
|
|
467
|
+
|
|
468
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML" valid="true">
|
|
469
|
+
<teieg-constraintspec data-teiname="constraintSpec" ident="calendar" scheme="isoschematron">
|
|
470
|
+
<teieg-constraint data-teiname="constraint">
|
|
471
|
+
<sch:rule xmlns:sch="http://purl.oclc.org/dsdl/schematron" context="tei:*[@calendar]">
|
|
472
|
+
<sch:assert test="string-length(.) gt 0">
|
|
473
|
+
@calendar indicates the system or calendar
|
|
474
|
+
to which the date represented by the content
|
|
475
|
+
of this element belongs, but this element
|
|
476
|
+
has no textual content.
|
|
477
|
+
</sch:assert>
|
|
478
|
+
</sch:rule>
|
|
479
|
+
</teieg-constraint>
|
|
480
|
+
</teieg-constraintspec>
|
|
481
|
+
</teieg-egxml>
|
|
482
|
+
|
|
483
|
+
(Obviously, by the time you're reading this, the <tei-gi data-origname="gi">constraintSpec</tei-gi> is already in the TEI source, so you'll see it there.) If the Schematron namespace is not
|
|
484
|
+
already defined somewhere in the file, we'll also have to make sure we add it; in this case, I defined the prefix in the <tei-gi data-origname="gi">classSpec</tei-gi> root element:
|
|
485
|
+
<tei-code data-origname="code">xmlns:sch="http://purl.oclc.org/dsdl/schematron"</tei-code>. Then we commit our changes, and let the TEI build process build all the products, and make sure that
|
|
486
|
+
we didn't get anything wrong.</tei-p>
|
|
487
|
+
|
|
488
|
+
<tei-p data-origname="p">When writing Schematron constraints for the Guidelines, bear these points in mind:
|
|
489
|
+
<tei-list data-origname="list">
|
|
490
|
+
<tei-item data-origname="item">Ensure that the context item for the rule is an element, not an attribute, as in the example above. For technical reasons, the Schematron processing in the build process will generate error messages if the context item is an attribute.</tei-item>
|
|
491
|
+
<tei-item data-origname="item">Break up the message up into fairly short lines, so that it's easy to read when it appears in the build log.</tei-item>
|
|
492
|
+
<tei-item data-origname="item">Use the <tei-gi data-origname="gi">name</tei-gi> element in place of the name of the context element. This will be helpful for future processing needs. </tei-item>
|
|
493
|
+
<tei-item data-origname="item">Refer to attributes using the "@" prefix, rather than quotation marks or plain names (as above).</tei-item>
|
|
494
|
+
</tei-list>
|
|
495
|
+
|
|
496
|
+
</tei-p>
|
|
497
|
+
|
|
498
|
+
<tei-p data-origname="p">The Schematron constraint above should cover what we're trying to accomplish. However, it's quite difficult for us to test whether it is in fact doing exactly what it should be, unless we build a new copy of Roma
|
|
499
|
+
and use it to generate a Schematron schema, then validate a test document against it. This is probably not practical for most of us. Fortunately, the TEI build system provides a
|
|
500
|
+
way for us to do this; in fact, we can put in place a couple of tests that will always be run whenever P5 is built, checking that our Schematron constraint is intact and functioning
|
|
501
|
+
as we expect. </tei-p>
|
|
502
|
+
|
|
503
|
+
<tei-p data-origname="p">The first thing we're going to do is add a couple of tests that should pass. We'll add a dating element which has both <tei-att data-origname="att">calendar</tei-att> and some textual content, as well as an
|
|
504
|
+
empty dating element with no textual content. If these tests pass, then we know that our constraint is not doing anything wrong. (We don't yet know whether it's doing anything at
|
|
505
|
+
all, of course; that comes later.) </tei-p>
|
|
506
|
+
|
|
507
|
+
<tei-p data-origname="p">If you look at <tei-ident data-origname="ident">trunk/P5/Test</tei-ident>, you'll see there is a whole folder full of files whose purpose is to test various aspects of the TEI build process and products. We want to add
|
|
508
|
+
our tests to one of these files. The question is which one? We'll add it to the basic test file, which is <tei-ident data-origname="ident">testbasic.xml</tei-ident>; this is tested against schemas generated from <tei-ident data-origname="ident">testbasic.odd</tei-ident>,
|
|
509
|
+
which should contain all the dating features we're interested in testing. If we look at that file, we find there are already several date elements in there, so we can try adding our
|
|
510
|
+
<tei-att data-origname="att">calendar</tei-att> attribute to one of those. Let's choose the date of 1685 on a dictionary entry sense:
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML" valid="true">
|
|
514
|
+
<teieg-sense data-teiname="sense">
|
|
515
|
+
<teieg-date data-teiname="date" calendar="http://en.wikipedia.org/wiki/Julian_calendar">1685</teieg-date>
|
|
516
|
+
<teieg-form data-teiname="form">
|
|
517
|
+
<teieg-orth data-teiname="orth">pamplemousse </teieg-orth>
|
|
518
|
+
</teieg-form>
|
|
519
|
+
</teieg-sense>
|
|
520
|
+
</teieg-egxml>
|
|
521
|
+
|
|
522
|
+
We could go to the trouble of adding <tei-gi data-origname="gi">calendarDesc</tei-gi> and <tei-gi data-origname="gi">calendar</tei-gi> to the header of the file so we can point to a calendar element in the same document,
|
|
523
|
+
but since <tei-att data-origname="att">calendar</tei-att> is a <tei-ident data-origname="ident">data.pointer</tei-ident>, we can point to an external source of calendar information.</tei-p>
|
|
524
|
+
|
|
525
|
+
<tei-p data-origname="p">We also want to add, somewhere, a date element which has no textual content and no <tei-att data-origname="att">calendar</tei-att> attribute. We might as well do this in the header,
|
|
526
|
+
by adding a simple <tei-gi data-origname="gi">revisionDesc</tei-gi> element, which gives us the added bonus of being able to describe our change:
|
|
527
|
+
|
|
528
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML" valid="true">
|
|
529
|
+
<teieg-revisiondesc data-teiname="revisionDesc">
|
|
530
|
+
<teieg-change data-teiname="change"><date when="2012-09-06"/>MDH: Added @calendar to one date, and the date
|
|
531
|
+
element in here, for testing a new Schematron constraint.</teieg-change>
|
|
532
|
+
</teieg-revisiondesc>
|
|
533
|
+
</teieg-egxml>
|
|
534
|
+
|
|
535
|
+
|
|
536
|
+
Now we can commit our change, and see if the build of TEIP5-Test completes successfully on our Jenkins servers.</tei-p>
|
|
537
|
+
|
|
538
|
+
<tei-p data-origname="p">If that build successfully completes, we haven't broken anything. But we still don't know whether our constraint will actually fire when something is wrong.
|
|
539
|
+
In order to do that, we have to use the "detest" system. In <tei-ident data-origname="ident">trunk/P5/Test</tei-ident>, you'll find the following files:
|
|
540
|
+
|
|
541
|
+
<tei-list data-origname="list">
|
|
542
|
+
<tei-item data-origname="item"><tei-ident data-origname="ident">expected-results/detest.log</tei-ident></tei-item>
|
|
543
|
+
<tei-item data-origname="item"><tei-ident data-origname="ident">detest.odd</tei-ident></tei-item>
|
|
544
|
+
<tei-item data-origname="item"><tei-ident data-origname="ident">detest.xml</tei-ident></tei-item>
|
|
545
|
+
</tei-list>
|
|
546
|
+
|
|
547
|
+
detest.odd and detest.xml are test files like the ones we've seen above, but the purpose of the <tei-socalled data-origname="soCalled">detest</tei-socalled> files is to introduce deliberate errors and make sure that the testing process throws up the expected error results. What happens is basically this:
|
|
548
|
+
|
|
549
|
+
<tei-list data-origname="list">
|
|
550
|
+
<tei-item data-origname="item">Schemas are built from detest.odd (including a Schematron schema).</tei-item>
|
|
551
|
+
<tei-item data-origname="item">The file <tei-ident data-origname="ident">detest.xml</tei-ident> is validated against those schemas.</tei-item>
|
|
552
|
+
<tei-item data-origname="item">Resulting error messages are collected in a file called <tei-ident data-origname="ident">detest.log</tei-ident> (in the Test directory).</tei-item>
|
|
553
|
+
<tei-item data-origname="item">That file is compared with the <tei-ident data-origname="ident">detest.log</tei-ident> file in the <tei-ident data-origname="ident">expected-results</tei-ident> subdirectory.</tei-item>
|
|
554
|
+
<tei-item data-origname="item">If they are not identical, the test build fails.</tei-item>
|
|
555
|
+
</tei-list>
|
|
556
|
+
|
|
557
|
+
So what we need to do is to add some new markup to <tei-ident data-origname="ident">detest.xml</tei-ident> which is designed to fail our Schematron test. The problem is that we cannot reliably predict how it will fail—in other words, we can't know in advance what the resulting <tei-ident data-origname="ident">detest.log</tei-ident> file should look like, because we can't know in what order the tests will run, and what the precise error messages might be. We could find this out if we had a working local build environment of our own, but it's far simpler to let Jenkins do the job for us. So this is what we'll do:
|
|
558
|
+
|
|
559
|
+
<tei-list data-origname="list">
|
|
560
|
+
<tei-item data-origname="item">Add our new test to <tei-ident data-origname="ident">detest.xml</tei-ident>.</tei-item>
|
|
561
|
+
<tei-item data-origname="item">Commit the change to the git repository.</tei-item>
|
|
562
|
+
<tei-item data-origname="item">Let Jenkins run the build (which should fail).</tei-item>
|
|
563
|
+
<tei-item data-origname="item">Examine the resulting <tei-ident data-origname="ident">detest.log</tei-ident> on Jenkins, and copy it to our local <tei-ident data-origname="ident">expected-results/detest.log</tei-ident>.</tei-item>
|
|
564
|
+
<tei-item data-origname="item">Commit that change to the repository.</tei-item>
|
|
565
|
+
<tei-item data-origname="item">Let Jenkins build again, and make sure that the build completes successfully.</tei-item>
|
|
566
|
+
</tei-list>
|
|
567
|
+
|
|
568
|
+
We'll add this div to the <tei-ident data-origname="ident">detest.xml</tei-ident> file:
|
|
569
|
+
|
|
570
|
+
|
|
571
|
+
<teieg-egxml data-xmlns="http://www.tei-c.org/ns/Examples" data-teiname="egXML" valid="false">
|
|
572
|
+
<teieg-div data-teiname="div">
|
|
573
|
+
<teieg-p data-teiname="p">Added by MDH. This tests the Schematron constraint that any element with
|
|
574
|
+
@calendar must have some textual content.</teieg-p>
|
|
575
|
+
<teieg-p data-teiname="p"><teieg-date data-teiname="date" when="2012-09-06" calendar="http://en.wikipedia.org/wiki/Gregorian_calendar"></teieg-date></teieg-p>
|
|
576
|
+
</teieg-div>
|
|
577
|
+
</teieg-egxml>
|
|
578
|
+
|
|
579
|
+
Now we commit the change to git, and Jenkins will start building. The build should fail, and it does. If we now go to the Jenkins workspace on one of our two build servers:
|
|
580
|
+
|
|
581
|
+
<tei-list data-origname="list">
|
|
582
|
+
<tei-item data-origname="item"><tei-ref data-origname="ref" data-origatts="target" target="https://jenkins.tei-c.org/job/TEIP5-Test-dev/ws/P5/Test/">https://jenkins.tei-c.org/job/TEIP5-Test-dev/ws/P5/Test/</tei-ref></tei-item>
|
|
583
|
+
<tei-item data-origname="item"><tei-ref data-origname="ref" data-origatts="target" target="https://jenkins2.tei-c.org/job/TEIP5-Test-dev/ws/P5/Test/">https://jenkins2.tei-c.org/job/TEIP5-Test-dev/ws/P5/Test/</tei-ref></tei-item>
|
|
584
|
+
</tei-list>
|
|
585
|
+
|
|
586
|
+
we'll see a file called <tei-ident data-origname="ident">detest.log</tei-ident>, and if we look inside it, we'll find this bit, generated by our constraint:
|
|
587
|
+
|
|
588
|
+
<tei-q data-origname="q">@calendar indicates the system or calendar to which the date represented by the content of this element belongs, but this element has no textual content. (string-length(.) gt 0)</tei-q>
|
|
589
|
+
|
|
590
|
+
This line is obviously missing from <tei-ident data-origname="ident">expected-results/detest.log</tei-ident>, so the build failed when the two files were compared. We can fix that very simply:
|
|
591
|
+
|
|
592
|
+
<tei-list data-origname="list">
|
|
593
|
+
<tei-item data-origname="item">Download the <tei-ident data-origname="ident">detest.log</tei-ident> file from the TEIP5-Test workspace on the Jenkins server (<tei-ident data-origname="ident">job/TEIP5-Test/ws/Test/</tei-ident>).</tei-item>
|
|
594
|
+
<tei-item data-origname="item">Copy its contents into our local file <tei-ident data-origname="ident">expected-results/detest.log</tei-ident>.</tei-item>
|
|
595
|
+
<tei-item data-origname="item">Commit this change to git (git commit followed by git push).</tei-item>
|
|
596
|
+
<tei-item data-origname="item">Watch Jenkins build P5-Test again, and make sure it completes successfully.</tei-item>
|
|
597
|
+
</tei-list>
|
|
598
|
+
</tei-p>
|
|
599
|
+
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
</tei-div>
|
|
603
|
+
|
|
604
|
+
<tei-div id="release" data-origname="div" data-origatts="id" xml:id="release">
|
|
605
|
+
<tei-head data-origname="head">Building the release</tei-head>
|
|
606
|
+
|
|
607
|
+
<tei-p data-origname="p">Note: the original content of this section has been removed, because a longer document dedicated to
|
|
608
|
+
documenting the release process has been created. Please refer to <tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Activities/Council/Working/tcw22.xml">TCW22: Building a TEI Release</tei-ref>.</tei-p>
|
|
609
|
+
|
|
610
|
+
<!-- Content deleted by mholmes 2012-02-13. -->
|
|
611
|
+
</tei-div>
|
|
612
|
+
|
|
613
|
+
|
|
614
|
+
<tei-div data-origname="div">
|
|
615
|
+
<tei-head data-origname="head">Reference section</tei-head>
|
|
616
|
+
<tei-div id="chaptercodes" data-origname="div" data-origatts="id" xml:id="chaptercodes">
|
|
617
|
+
<tei-head data-origname="head">Chapter codes</tei-head>
|
|
618
|
+
<tei-p data-origname="p">Following a lengthy debate in the Council as to whether the
|
|
619
|
+
two-character codes originally used to identify individual chapters
|
|
620
|
+
should be dropped in favour of longer more human-readable names, a
|
|
621
|
+
compromise solution was reached in which the two character codes were
|
|
622
|
+
retained as prefixes to longer human-readable names. The same
|
|
623
|
+
two-character codes are also used to identify the HTML and PDF files
|
|
624
|
+
generated during the release process.</tei-p>
|
|
625
|
+
<tei-p data-origname="p">The following
|
|
626
|
+
table shows the correspondence between the printed organization of the
|
|
627
|
+
Guidelines and the corresponding filenames. The order is determined by the
|
|
628
|
+
driver file <tei-ident data-origname="ident">Source/guidelines-xx.xml</tei-ident>, from which the
|
|
629
|
+
table is derived.
|
|
630
|
+
<tei-table data-origname="table">
|
|
631
|
+
<tei-row data-origname="row" data-origatts="role" role="label"><tei-cell data-origname="cell">Section</tei-cell><tei-cell data-origname="cell">Title</tei-cell><tei-cell data-origname="cell">filename</tei-cell></tei-row>
|
|
632
|
+
<tei-row data-origname="row">
|
|
633
|
+
<tei-cell data-origname="cell">[i]</tei-cell><tei-cell data-origname="cell">Releases of the TEI Guidelines</tei-cell>
|
|
634
|
+
<tei-cell data-origname="cell">TitlePageVerso.xml</tei-cell></tei-row>
|
|
635
|
+
<tei-row data-origname="row">
|
|
636
|
+
<tei-cell data-origname="cell">[ii]</tei-cell><tei-cell data-origname="cell">Dedication</tei-cell>
|
|
637
|
+
<tei-cell data-origname="cell">Dedication.xml</tei-cell></tei-row>
|
|
638
|
+
<tei-row data-origname="row">
|
|
639
|
+
<tei-cell data-origname="cell">[iii]</tei-cell><tei-cell data-origname="cell">Preface and Acknowledgments</tei-cell>
|
|
640
|
+
<tei-cell data-origname="cell">FM1-IntroductoryNote.xml</tei-cell></tei-row>
|
|
641
|
+
<tei-row data-origname="row">
|
|
642
|
+
<tei-cell data-origname="cell">[iv]</tei-cell><tei-cell data-origname="cell">About These Guidelines</tei-cell>
|
|
643
|
+
<tei-cell data-origname="cell">AB-About.xml</tei-cell></tei-row>
|
|
644
|
+
<tei-row data-origname="row">
|
|
645
|
+
<tei-cell data-origname="cell">[v]</tei-cell><tei-cell data-origname="cell">A Gentle Introduction to XML</tei-cell>
|
|
646
|
+
<tei-cell data-origname="cell">SG-GentleIntroduction.xml</tei-cell></tei-row>
|
|
647
|
+
<tei-row data-origname="row">
|
|
648
|
+
<tei-cell data-origname="cell">[vi]</tei-cell><tei-cell data-origname="cell">Languages and Character Sets</tei-cell>
|
|
649
|
+
<tei-cell data-origname="cell">CH-LanguagesCharacterSets.xml</tei-cell></tei-row>
|
|
650
|
+
<tei-row data-origname="row">
|
|
651
|
+
<tei-cell data-origname="cell">[1]</tei-cell><tei-cell data-origname="cell">The TEI Infrastructure</tei-cell>
|
|
652
|
+
<tei-cell data-origname="cell">ST-Infrastructure.xml</tei-cell></tei-row>
|
|
653
|
+
<tei-row data-origname="row">
|
|
654
|
+
<tei-cell data-origname="cell">[2]</tei-cell><tei-cell data-origname="cell">The TEI Header</tei-cell>
|
|
655
|
+
<tei-cell data-origname="cell">HD-Header.xml</tei-cell></tei-row>
|
|
656
|
+
<tei-row data-origname="row">
|
|
657
|
+
<tei-cell data-origname="cell">[3]</tei-cell><tei-cell data-origname="cell">Elements Available in All TEI Documents</tei-cell>
|
|
658
|
+
<tei-cell data-origname="cell">CO-CoreElements.xml</tei-cell></tei-row>
|
|
659
|
+
<tei-row data-origname="row">
|
|
660
|
+
<tei-cell data-origname="cell">[4]</tei-cell><tei-cell data-origname="cell">Default Text Structure</tei-cell>
|
|
661
|
+
<tei-cell data-origname="cell">DS-DefaultTextStructure.xml</tei-cell></tei-row>
|
|
662
|
+
<tei-row data-origname="row">
|
|
663
|
+
<tei-cell data-origname="cell">[5]</tei-cell><tei-cell data-origname="cell">Representation of Non-standard Characters and
|
|
664
|
+
Glyphs</tei-cell><tei-cell data-origname="cell">WD-NonStandardCharacters.xml</tei-cell>
|
|
665
|
+
</tei-row>
|
|
666
|
+
<tei-row data-origname="row">
|
|
667
|
+
<tei-cell data-origname="cell">[6]</tei-cell><tei-cell data-origname="cell">Verse</tei-cell><tei-cell data-origname="cell">VE-Verse.xml</tei-cell>
|
|
668
|
+
</tei-row>
|
|
669
|
+
<tei-row data-origname="row">
|
|
670
|
+
<tei-cell data-origname="cell">[7]</tei-cell><tei-cell data-origname="cell">Performance Texts</tei-cell>
|
|
671
|
+
<tei-cell data-origname="cell">DR-PerformanceTexts.xml</tei-cell></tei-row>
|
|
672
|
+
<tei-row data-origname="row">
|
|
673
|
+
<tei-cell data-origname="cell">[8]</tei-cell><tei-cell data-origname="cell">Transcriptions of Speech</tei-cell>
|
|
674
|
+
<tei-cell data-origname="cell">TS-TranscriptionsofSpeech.xml</tei-cell></tei-row>
|
|
675
|
+
<tei-row data-origname="row">
|
|
676
|
+
<tei-cell data-origname="cell">[9]</tei-cell><tei-cell data-origname="cell">Dictionaries</tei-cell>
|
|
677
|
+
<tei-cell data-origname="cell">DI-PrintDictionaries.xml</tei-cell></tei-row>
|
|
678
|
+
<tei-row data-origname="row">
|
|
679
|
+
<tei-cell data-origname="cell">[10]</tei-cell><tei-cell data-origname="cell">Manuscript Description</tei-cell>
|
|
680
|
+
<tei-cell data-origname="cell">MS-ManuscriptDescription.xml</tei-cell></tei-row>
|
|
681
|
+
<tei-row data-origname="row">
|
|
682
|
+
<tei-cell data-origname="cell">[11]</tei-cell><tei-cell data-origname="cell">Representation of Primary Sources</tei-cell>
|
|
683
|
+
<tei-cell data-origname="cell">PH-PrimarySources.xml</tei-cell></tei-row>
|
|
684
|
+
<tei-row data-origname="row">
|
|
685
|
+
<tei-cell data-origname="cell">[12]</tei-cell><tei-cell data-origname="cell">Critical Apparatus</tei-cell>
|
|
686
|
+
<tei-cell data-origname="cell">TC-CriticalApparatus.xml</tei-cell></tei-row>
|
|
687
|
+
<tei-row data-origname="row">
|
|
688
|
+
<tei-cell data-origname="cell">[13]</tei-cell><tei-cell data-origname="cell">Names, Dates, People, and Places</tei-cell>
|
|
689
|
+
<tei-cell data-origname="cell">ND-NamesDates.xml</tei-cell></tei-row>
|
|
690
|
+
<tei-row data-origname="row">
|
|
691
|
+
<tei-cell data-origname="cell">[14]</tei-cell><tei-cell data-origname="cell">Tables, Formulæ, and Graphics</tei-cell>
|
|
692
|
+
<tei-cell data-origname="cell">FT-TablesFormulaeGraphics.xml</tei-cell></tei-row>
|
|
693
|
+
<tei-row data-origname="row">
|
|
694
|
+
<tei-cell data-origname="cell">[15]</tei-cell><tei-cell data-origname="cell">Language Corpora</tei-cell>
|
|
695
|
+
<tei-cell data-origname="cell">CC-LanguageCorpora.xml</tei-cell></tei-row>
|
|
696
|
+
<tei-row data-origname="row">
|
|
697
|
+
<tei-cell data-origname="cell">[16]</tei-cell><tei-cell data-origname="cell">Linking, Segmentation, and Alignment</tei-cell>
|
|
698
|
+
<tei-cell data-origname="cell">SA-LinkingSegmentationAlignment.xml</tei-cell></tei-row>
|
|
699
|
+
<tei-row data-origname="row">
|
|
700
|
+
<tei-cell data-origname="cell">[17]</tei-cell><tei-cell data-origname="cell">Simple Analytic Mechanisms</tei-cell>
|
|
701
|
+
<tei-cell data-origname="cell">AI-AnalyticMechanisms.xml</tei-cell></tei-row>
|
|
702
|
+
<tei-row data-origname="row">
|
|
703
|
+
<tei-cell data-origname="cell">[18]</tei-cell><tei-cell data-origname="cell">Feature Structures</tei-cell>
|
|
704
|
+
<tei-cell data-origname="cell">FS-FeatureStructures.xml</tei-cell></tei-row>
|
|
705
|
+
<tei-row data-origname="row">
|
|
706
|
+
<tei-cell data-origname="cell">[19]</tei-cell><tei-cell data-origname="cell">Graphs, Networks, and Trees</tei-cell>
|
|
707
|
+
<tei-cell data-origname="cell">GD-GraphsNetworksTrees.xml</tei-cell></tei-row>
|
|
708
|
+
<tei-row data-origname="row">
|
|
709
|
+
<tei-cell data-origname="cell">[20]</tei-cell><tei-cell data-origname="cell">Non-hierarchical Structures</tei-cell>
|
|
710
|
+
<tei-cell data-origname="cell">NH-Non-hierarchical.xml</tei-cell></tei-row>
|
|
711
|
+
<tei-row data-origname="row">
|
|
712
|
+
<tei-cell data-origname="cell">[21]</tei-cell><tei-cell data-origname="cell">Certainty, Precision, and Responsibility</tei-cell>
|
|
713
|
+
<tei-cell data-origname="cell">CE-CertaintyResponsibility.xml</tei-cell></tei-row>
|
|
714
|
+
<tei-row data-origname="row">
|
|
715
|
+
<tei-cell data-origname="cell">[22]</tei-cell><tei-cell data-origname="cell">Documentation Elements</tei-cell>
|
|
716
|
+
<tei-cell data-origname="cell">TD-DocumentationElements.xml</tei-cell></tei-row>
|
|
717
|
+
<tei-row data-origname="row">
|
|
718
|
+
<tei-cell data-origname="cell">[23]</tei-cell><tei-cell data-origname="cell">Using the TEI</tei-cell>
|
|
719
|
+
<tei-cell data-origname="cell">USE.xml</tei-cell></tei-row>
|
|
720
|
+
<tei-row data-origname="row">
|
|
721
|
+
<tei-cell data-origname="cell">[A1]</tei-cell><tei-cell data-origname="cell">Model Classes</tei-cell>
|
|
722
|
+
<tei-cell data-origname="cell">REF-CLASSES-MODEL.xml</tei-cell></tei-row>
|
|
723
|
+
<tei-row data-origname="row">
|
|
724
|
+
<tei-cell data-origname="cell">[A2]</tei-cell><tei-cell data-origname="cell">Attribute Classes</tei-cell>
|
|
725
|
+
<tei-cell data-origname="cell">REF-CLASSES-ATTS.xml</tei-cell></tei-row>
|
|
726
|
+
<tei-row data-origname="row">
|
|
727
|
+
<tei-cell data-origname="cell">[A3]</tei-cell><tei-cell data-origname="cell">Elements</tei-cell>
|
|
728
|
+
<tei-cell data-origname="cell">REF-ELEMENTS.xml</tei-cell></tei-row>
|
|
729
|
+
<tei-row data-origname="row">
|
|
730
|
+
<tei-cell data-origname="cell">[A4]</tei-cell><tei-cell data-origname="cell">Attributes</tei-cell>
|
|
731
|
+
<tei-cell data-origname="cell">REF-ATTRIBUTES.xml</tei-cell></tei-row>
|
|
732
|
+
<tei-row data-origname="row">
|
|
733
|
+
<tei-cell data-origname="cell">[A5]</tei-cell><tei-cell data-origname="cell">Datatypes and Other Macros</tei-cell>
|
|
734
|
+
<tei-cell data-origname="cell">REF-MACROS.xml</tei-cell></tei-row>
|
|
735
|
+
<tei-row data-origname="row">
|
|
736
|
+
<tei-cell data-origname="cell">[A6]</tei-cell><tei-cell data-origname="cell">Bibliography</tei-cell>
|
|
737
|
+
<tei-cell data-origname="cell">BIB-Bibliography.xml</tei-cell></tei-row>
|
|
738
|
+
<tei-row data-origname="row">
|
|
739
|
+
<tei-cell data-origname="cell">[A7]</tei-cell><tei-cell data-origname="cell">Prefatory Notes</tei-cell>
|
|
740
|
+
<tei-cell data-origname="cell">PrefatoryNote.xml</tei-cell></tei-row>
|
|
741
|
+
<tei-row data-origname="row">
|
|
742
|
+
<tei-cell data-origname="cell">[A8]</tei-cell><tei-cell data-origname="cell">Colophon</tei-cell>
|
|
743
|
+
<tei-cell data-origname="cell">COL-Colophon.xml</tei-cell></tei-row></tei-table>
|
|
744
|
+
</tei-p>
|
|
745
|
+
<tei-p data-origname="p">In most chapters, the two character code is also used as a prefix
|
|
746
|
+
for the <tei-att data-origname="att">xml:id</tei-att> values given to each <tei-gi data-origname="gi">div</tei-gi>
|
|
747
|
+
element. Note that every <tei-gi data-origname="gi">div</tei-gi> element carries an
|
|
748
|
+
<tei-att data-origname="att">xml:id</tei-att> value, whether or not it is actually referenced
|
|
749
|
+
explicitly elewhere in the Guidelines.
|
|
750
|
+
</tei-p>
|
|
751
|
+
<tei-p data-origname="p">Note that files with names beginning <tei-code data-origname="code">REF</tei-code> contain
|
|
752
|
+
only <tei-gi data-origname="gi">divGen</tei-gi> elements: their content, which provides the
|
|
753
|
+
reference documentation (sections A1 to A5 inclusive), is
|
|
754
|
+
automatically generated during the build process.</tei-p>
|
|
755
|
+
</tei-div>
|
|
756
|
+
<tei-div data-origname="div">
|
|
757
|
+
<tei-head data-origname="head">Naming conventions</tei-head>
|
|
758
|
+
<tei-p data-origname="p">TEI naming conventions have evolved over time, but remain fairly consistent. </tei-p>
|
|
759
|
+
<tei-list data-origname="list" data-origatts="type" type="gloss">
|
|
760
|
+
<tei-label data-origname="label">generic identifiers</tei-label>
|
|
761
|
+
<tei-item data-origname="item">An element and attribute identifiers should be a single natural language word in
|
|
762
|
+
lowercase if possible. If more than one word is conjoined to form a name, then the
|
|
763
|
+
first letter of the second and any subsequent word should be uppercased. Hyphens,
|
|
764
|
+
underscores, dots etc are not used within element or attribute names. </tei-item>
|
|
765
|
+
<tei-label data-origname="label">class names</tei-label>
|
|
766
|
+
<tei-item data-origname="item">Class names are made up three parts: a name, constructed like an element name,
|
|
767
|
+
with a prefix and optionally a suffix. The prefix is one of <tei-code data-origname="code">model.</tei-code> or
|
|
768
|
+
<tei-code data-origname="code">att.</tei-code> and indicates whether this is a model or an attribute class. The
|
|
769
|
+
suffix, if present, is used to indicate subclassing: for example
|
|
770
|
+
<tei-ident data-origname="ident">att.linking.foo</tei-ident> is the <tei-ident data-origname="ident">foo</tei-ident> subclass of the attribute
|
|
771
|
+
class <tei-ident data-origname="ident">att.linking</tei-ident></tei-item>
|
|
772
|
+
<tei-label data-origname="label">xml:id values</tei-label>
|
|
773
|
+
<tei-item data-origname="item">The conventions for these vary somewhat. Most of the older chapters of the
|
|
774
|
+
guidelines have consistently constructed identifiers, derived from the individual
|
|
775
|
+
section headings. Identifiers must be provided for:<tei-list data-origname="list">
|
|
776
|
+
<tei-item data-origname="item">every <tei-gi data-origname="gi">div</tei-gi>, whether or not it is explicitly linked to elsewhere</tei-item>
|
|
777
|
+
<tei-item data-origname="item">every bibliographic reference in the <tei-ident data-origname="ident">BIB-Bibliography.xml</tei-ident> file</tei-item>
|
|
778
|
+
</tei-list></tei-item>
|
|
779
|
+
</tei-list>
|
|
780
|
+
</tei-div>
|
|
781
|
+
<tei-div id="fileOrg" data-origname="div" data-origatts="id" xml:id="fileOrg"><tei-head data-origname="head">File release structure</tei-head>
|
|
782
|
+
<tei-p data-origname="p">
|
|
783
|
+
Currently, the organisation of the <tei-code data-origname="code">/usr/share/xml/tei</tei-code> and
|
|
784
|
+
<tei-code data-origname="code">/usr/share/doc/tei-*</tei-code> directories on the TEI web site is
|
|
785
|
+
as follows:
|
|
786
|
+
<tei-eg data-origname="eg">
|
|
787
|
+
tei
|
|
788
|
+
|-- Test
|
|
789
|
+
|-- custom
|
|
790
|
+
| |-- odd
|
|
791
|
+
| |-- schema
|
|
792
|
+
| | |-- dtd
|
|
793
|
+
| | |-- relaxng
|
|
794
|
+
| | `-- xsd
|
|
795
|
+
| `-- templates
|
|
796
|
+
|-- odd
|
|
797
|
+
| |-- Exemplars
|
|
798
|
+
| |-- ReleaseNotes
|
|
799
|
+
| |-- Source
|
|
800
|
+
| | |-- Guidelines
|
|
801
|
+
| | | |-- en
|
|
802
|
+
| | | | `-- Images
|
|
803
|
+
| | | `-- fr
|
|
804
|
+
| | | `-- Images
|
|
805
|
+
| | |-- Images
|
|
806
|
+
| | `-- Specs
|
|
807
|
+
| | |-- 18decembre
|
|
808
|
+
| | `-- exemples
|
|
809
|
+
| |-- Utilities
|
|
810
|
+
| `-- webnav
|
|
811
|
+
| `-- icons
|
|
812
|
+
|-- schema
|
|
813
|
+
| |-- dtd
|
|
814
|
+
| `-- relaxng
|
|
815
|
+
|-- stylesheet
|
|
816
|
+
| |-- common
|
|
817
|
+
| |-- common2
|
|
818
|
+
| |-- docx
|
|
819
|
+
| | |-- from
|
|
820
|
+
| | | |-- dynamic
|
|
821
|
+
| | | | `-- tests
|
|
822
|
+
| | | | `-- xspec
|
|
823
|
+
| | | |-- graphics
|
|
824
|
+
| | | |-- lists
|
|
825
|
+
| | | |-- marginals
|
|
826
|
+
| | | |-- maths
|
|
827
|
+
| | | |-- paragraphs
|
|
828
|
+
| | | |-- pass0
|
|
829
|
+
| | | |-- pass2
|
|
830
|
+
| | | |-- tables
|
|
831
|
+
| | | |-- templates
|
|
832
|
+
| | | |-- textruns
|
|
833
|
+
| | | |-- utils
|
|
834
|
+
| | | `-- wordsections
|
|
835
|
+
| | |-- misc
|
|
836
|
+
| | |-- to
|
|
837
|
+
| | | |-- docxfiles
|
|
838
|
+
| | | |-- drama
|
|
839
|
+
| | | |-- dynamic
|
|
840
|
+
| | | |-- graphics
|
|
841
|
+
| | | |-- lists
|
|
842
|
+
| | | |-- maths
|
|
843
|
+
| | | |-- templates
|
|
844
|
+
| | | `-- wordsections
|
|
845
|
+
| | `-- utils
|
|
846
|
+
| | |-- graphics
|
|
847
|
+
| | |-- identity
|
|
848
|
+
| | |-- maths
|
|
849
|
+
| | `-- verbatim
|
|
850
|
+
| |-- epub
|
|
851
|
+
| |-- fo
|
|
852
|
+
| |-- fo2
|
|
853
|
+
| |-- html
|
|
854
|
+
| |-- latex
|
|
855
|
+
| |-- latex2
|
|
856
|
+
| |-- nlm
|
|
857
|
+
| |-- odds
|
|
858
|
+
| |-- odds2
|
|
859
|
+
| |-- oo
|
|
860
|
+
| |-- profiles
|
|
861
|
+
| | |-- bodley
|
|
862
|
+
| | | `-- epub
|
|
863
|
+
| | |-- default
|
|
864
|
+
| | | |-- csv
|
|
865
|
+
| | | |-- docbook
|
|
866
|
+
| | | |-- docx
|
|
867
|
+
| | | |-- dtd
|
|
868
|
+
| | | |-- epub
|
|
869
|
+
| | | |-- fo
|
|
870
|
+
| | | |-- html
|
|
871
|
+
| | | |-- latex
|
|
872
|
+
| | | |-- lite
|
|
873
|
+
| | | |-- oddhtml
|
|
874
|
+
| | | |-- oo
|
|
875
|
+
| | | |-- p4
|
|
876
|
+
| | | `-- relaxng
|
|
877
|
+
| | |-- enrich
|
|
878
|
+
| | | |-- docx
|
|
879
|
+
| | | |-- fo
|
|
880
|
+
| | | |-- html
|
|
881
|
+
| | | `-- latex
|
|
882
|
+
| | |-- iso
|
|
883
|
+
| | | |-- docx
|
|
884
|
+
| | | | `-- model
|
|
885
|
+
| | | |-- epub
|
|
886
|
+
| | | |-- fo
|
|
887
|
+
| | | |-- html
|
|
888
|
+
| | | |-- latex
|
|
889
|
+
| | | |-- schema
|
|
890
|
+
| | | `-- tbx
|
|
891
|
+
| | |-- ota
|
|
892
|
+
| | | |-- epub
|
|
893
|
+
| | | `-- html
|
|
894
|
+
| | |-- oucs
|
|
895
|
+
| | | |-- docx
|
|
896
|
+
| | | |-- epub
|
|
897
|
+
| | | `-- p4
|
|
898
|
+
| | |-- oucscourses
|
|
899
|
+
| | | `-- docx
|
|
900
|
+
| | |-- podcasts
|
|
901
|
+
| | | |-- docx
|
|
902
|
+
| | | `-- epub
|
|
903
|
+
| | `-- tei
|
|
904
|
+
| | `-- epub
|
|
905
|
+
| |-- slides
|
|
906
|
+
| |-- slides2
|
|
907
|
+
| |-- tite
|
|
908
|
+
| |-- tools2
|
|
909
|
+
| |-- xhtml
|
|
910
|
+
| `-- xhtml2
|
|
911
|
+
`-- xquery
|
|
912
|
+
|
|
913
|
+
</tei-eg>
|
|
914
|
+
</tei-p></tei-div>
|
|
915
|
+
|
|
916
|
+
</tei-div>
|
|
917
|
+
</tei-body>
|
|
918
|
+
<tei-back data-origname="back">
|
|
919
|
+
<tei-div data-origname="div" data-origatts="type" type="appendix">
|
|
920
|
+
<tei-head data-origname="head">Some other (mostly superceded) documents on the topic</tei-head>
|
|
921
|
+
|
|
922
|
+
<tei-listbibl data-origname="listBibl">
|
|
923
|
+
<tei-bibl data-origname="bibl"><tei-idno data-origname="idno">TEI ED W9</tei-idno>
|
|
924
|
+
<tei-title data-origname="title">Points of Style For Drafts of TEI Guidelines</tei-title>
|
|
925
|
+
<tei-date data-origname="date">2 Mar 1990</tei-date>
|
|
926
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw09.gml">in Waterloo Script format</tei-ref>
|
|
927
|
+
</tei-bibl>
|
|
928
|
+
|
|
929
|
+
<tei-bibl data-origname="bibl">
|
|
930
|
+
<tei-title data-origname="title">Notes on House Style</tei-title>
|
|
931
|
+
<tei-idno data-origname="idno">TEI ED W11</tei-idno>
|
|
932
|
+
<tei-date data-origname="date">14 Sep 1992</tei-date>
|
|
933
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw11.gml">in Waterloo script</tei-ref>
|
|
934
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw11.txt">formatted text</tei-ref>
|
|
935
|
+
</tei-bibl>
|
|
936
|
+
|
|
937
|
+
|
|
938
|
+
<tei-bibl data-origname="bibl"><tei-idno data-origname="idno">TEI ED W55</tei-idno>
|
|
939
|
+
<tei-title data-origname="title">Form for Draft Chapters of the TEI Guidelines</tei-title>
|
|
940
|
+
<tei-date data-origname="date">5 june 1996</tei-date>
|
|
941
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw55.tei">in TEI P2 format</tei-ref>
|
|
942
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw55.htm">in HTML format</tei-ref>
|
|
943
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw55.odd">in ODD format</tei-ref>
|
|
944
|
+
</tei-bibl>
|
|
945
|
+
|
|
946
|
+
<tei-bibl data-origname="bibl"><tei-idno data-origname="idno">TEI ED W57</tei-idno>
|
|
947
|
+
<tei-title data-origname="title">Procedures for Correcting Errors in the TEI Guidelines</tei-title>
|
|
948
|
+
<tei-date data-origname="date">July 23, 1994</tei-date>
|
|
949
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw57.tei">in TEI P2 format</tei-ref>
|
|
950
|
+
<tei-ref data-origname="ref" data-origatts="target" target="http://www.tei-c.org/Vault/ED/edw57.htm">in HTML format</tei-ref>
|
|
951
|
+
</tei-bibl>
|
|
952
|
+
|
|
953
|
+
</tei-listbibl>
|
|
954
|
+
</tei-div>
|
|
955
|
+
</tei-back> </tei-text>
|
|
956
|
+
</tei-tei>
|
|
957
|
+
<script type="text/javascript">
|
|
958
|
+
var c = new CETEI();
|
|
959
|
+
c.processPage();
|
|
960
|
+
</script></body></html>
|