Skip to content

Commit e77a679

Browse files
sydbsydb
committed
First crack at re-writing entire rationale section
1 parent a4c1835 commit e77a679

File tree

1 file changed

+112
-21
lines changed

1 file changed

+112
-21
lines changed

‎TCW/tcw31.xml‎

Lines changed: 112 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,11 @@
2525
</sourceDesc>
2626
</fileDesc>
2727
<revisionDesc>
28-
<change when="2025-12-03" who="#POC">Update procedure with the improved <code>/Test</code> process which moves
29-
comparisons to the end of Makefile, replaced <code>DIFFNOW=0</code> with <code>DIFFEND=1</code>.</change>
28+
<change when="2025-12-03" who="#POC">Update procedure with the
29+
improved process for <code>Test/</code>, which moves comparisons
30+
to the end of Makefile. It replaces <code>DIFFNOW=0</code>
31+
(which deferred comparisons completely, making the user do them
32+
manually) with <code>DIFFEND=1</code>.</change>
3033
<change when="2025-06-10" who="#POC">Revise and update procedure to keep it in line with
3134
current practices as outlined in the Council shared document</change>
3235
</revisionDesc>
@@ -35,26 +38,114 @@
3538
<body>
3639
<div>
3740
<head>TEI Council: Update P5 subset</head>
38-
<head>Rationale</head>
39-
<p>The Stylesheets tests can succeed only against either the release branch of P5, or the
40-
dev branch of P5, but often not against both simultaneously. For instance, the Stylesheets
41-
dev branch sometimes successfully builds against P5 release, but fails against P5 dev
42-
branch. On release day, we need the Stylesheets release branch to build against P5 release
43-
branch successfully i.e. we need the tests to work with the release branch against the
44-
release branch without producing any errors.</p>
45-
<p>Changes on either side (Stylesheets or Guidelines) may break either build. The
46-
Stylesheets test procedure in particular is quite fragile, and if it fails, the build
47-
fails. For instance, since the contents of <gi>desc</gi> elements are copied over into
48-
schemas, even a small change (like adding a comma) to an element description in the
49-
Guidelines might break the Stylesheets build. </p>
50-
<p>Since the Stylesheets are built against the Guidelines, there needs to be a (more or
51-
less) up-to-date copy of the Guidelines in the Stylesheet repository. This copy of the
52-
Guidelines is a file called “p5subset.xml” and it is stored in the <code>source/</code>
53-
directory. Building the Guidelines in the TEI repository does <hi rend="italics">not</hi>
54-
put a new copy of p5subset.xml into the <code>Stylesheets/source/</code> directory. In
55-
order to keep the version of the p5subset.xml in the Stylesheets repository up to date,
56-
that file is updated monthly by Council members. </p>
5741
<div>
42+
<head>Rationale</head>
43+
<p>Many of the Stylesheets’ tests generate schemas from the
44+
TEI Guidelines (using customization ODD files). This means
45+
that the test process needs to have access to a copy of
46+
P5. This in itself is not a particularly big problem — after
47+
all, there is always a copy available at <ptr
48+
target="https://www.tei-c.org/Vault/P5/current/xml/tei/odd/p5subset.xml"/>.
49+
But the way many of these tests work is to compare the
50+
schema generated by the test process with the expected
51+
schema: if they are the same, the test succeeds, if there
52+
is a difference, the test fails.</p>
53+
<p>On the face of it, this seems a sensible way to test. If
54+
you have changed the Stylesheets, you want to make sure your
55+
changes have not altered the generated schemas, at least not
56+
in a manner you did not expect. But this means there is an
57+
annoying dependency between the Guidelines and the
58+
Stylesheets’ test process, which itself is quite
59+
fragile.</p>
60+
<div>
61+
<head>dependency</head>
62+
<p>To understand the dependency problem, imagine that
63+
shortly after the release of P5 version 629.514.13 we drop
64+
the <gi>datatype</gi> element from the ODD language: the
65+
possible value(s) of an attribute are expressed with a
66+
<gi>dataRef</gi> rather than a <gi>dataRef</gi> inside a
67+
<gi>datatype</gi>. (This means that <gi>dataRef</gi> would
68+
need to become a member of <name
69+
type="class">att.repeatable</name>.) Once we change the
70+
Guidelines so that <gi>datatype</gi> is not an element, we
71+
need to actually remove <gi>datatype</gi> from the
72+
Guidelines, so that they remain valid.</p>
73+
<p>After these changes, we change the Stylesheets so that
74+
they know how to handle a <gi>dataRef</gi>, possibly with
75+
<att>minOccurs</att> or <att>maxOccurs</att>, that is a
76+
direct child of <gi>attDef</gi>. If we try to test the
77+
Stylesheets against P5 v. 629.514.13 (or any previous
78+
version) there will definitionally be no cases of a
79+
<gi>dataRef</gi> without <gi>datatype</gi> in the base
80+
ODD, because in that version of the Guidelines a
81+
<gi>dataRef</gi> was <emph>required</emph> to be inside a
82+
<gi>datatype</gi>. So (as long as we did not remove the
83+
code that handles a <gi>dataRef</gi> inside a
84+
<gi>datatype</gi>) the Stylesheets tests may not fail, but
85+
neither will they exercise our new code, that which we
86+
most need to test.</p>
87+
<p>So we need to tell the Stylesheets to use the new
88+
version of the Guidelines (v. 629.515.0α) as the base
89+
ODD. The way we do this is just to put a copy of the new
90+
version of the Guidelines into the Stylesheets repository.</p>
91+
</div>
92+
<div>
93+
<head>fragility</head>
94+
<p>Because the test procedure involves comparing two
95+
schemas (the actual output generated by the test, and the
96+
output that is expected from the test) using a string
97+
comparison tool, even very minor changes to the
98+
Guidelines may cause a test to fail. In fact, because the
99+
glosses and descriptions of XML constructs are included in
100+
the output schemas (so that tools like oXygen can make use
101+
of them), there are changes that do not change the actual
102+
XML defined by the schema, but nonetheless will cause a
103+
test to fail.</p>
104+
<p><label>Example 1</label> If the description of the
105+
<gi>constraint</gi> element were corrected from <quote>the
106+
formal rules of a constraint</quote> to <quote>contains
107+
the formal rules of a constraint.</quote>, every test that
108+
involves creating a schema that contains the
109+
<gi>constraint</gi> element would fail.</p>
110+
<p><label>Example 2</label> If the content model of the
111+
<gi>foo</gi> element were simplified from
112+
<egXML xmlns="http://www.tei-c.org/ns/Examples">
113+
<sequence>
114+
<elementRef key="bar"/>
115+
<elementRef key="bar"/>
116+
<elementRef key="bar" minOccurs="0" maxOccurs="unbounded"/>
117+
</sequence>
118+
</egXML>
119+
to just
120+
<egXML xmlns="http://www.tei-c.org/ns/Examples">
121+
<elementRef key="bar" minOccurs="2" maxOccurs="unbounded"/>
122+
</egXML>
123+
the same set of documents (those that have two or more
124+
<gi>bar</gi> elements as children of each <gi>foo</gi>)
125+
would be valid against the new schema. But since the
126+
actual grammar is different — it now has <code>bar,
127+
bar+</code> where it used to have <code>bar, bar,
128+
bar*</code>, the test would fail.</p>
129+
</div>
130+
<div>
131+
<head>solution</head>
132+
<p>Since the Stylesheets are tested against a specific
133+
version of the Guidelines, it is very helpful to have a
134+
(more or less) up-to-date copy of the Guidelines in the
135+
Stylesheet repository. If nothing else, this minimizes
136+
<q>used the wrong version of P5</q> situations.</p>
137+
<p>Thus we store a copy of the Guidelines in a file called
138+
<name type="file">p5subset.xml</name> in the
139+
<code>source/</code> directory. Just building the Guidelines
140+
in the TEI repository does <hi rend="italics">not</hi> put a
141+
new copy of p5subset.xml into the
142+
<code>Stylesheets/source/</code> directory. The file needs
143+
to be manually copied over, hence these instructions for
144+
doing so. This task is typically performed at least monthly
145+
by a Council member.</p>
146+
</div>
147+
</div>
148+
<div>
58149
<head>Step-by-Step Instructions:</head>
59150
<list rend="numbered">
60151
<item n="1">Update your local copies of both the TEI and Stylesheets

0 commit comments

Comments
 (0)