|
33 | 33 | <div> |
34 | 34 | <head>TEI Council: Update P5 subset</head> |
35 | 35 | <head>Rationale</head> |
36 | | - <p>The Stylesheets are built against the Guidelines, so there needs to be a (more |
37 | | - or less) up-to-date copy of the Guidelines in the Stylesheet repository. This copy of the Guidelines is a file called “p5subset.xml” and it is stored in the source/ directory. Building the Guidelines in the TEI repository does <hi rend="italics">not</hi> put a new copy of p5subset.xml into the Stylesheets/source/ directory. In order to keep the version of the p5subset.xml in the Stylesheets repository up to date, that file is updated monthly by Council members. |
| 36 | + <p>The Stylesheets tests can succeed only against either the release branch of P5, or the dev branch of P5, but often not against both simultaneously. For instance, the Stylesheets dev branch sometimes successfully builds against P5 release, but fails against P5 dev branch. On release day, when we need the Stylesheets release branch to build against P5 release branch, the tests work with the release branch against the release branch.</p> |
| 37 | + <p>Changes on either side (Stylesheets or Guidelines) may break either build because the Stylesheets test procedure is quite fragile, and if it fails, the build fails. In particular, since the contents of <gi>desc</gi> elements are copied over into schemas, even a small change (like adding a comma) to an element description in the Guidelines might break the Stylesheets build. |
| 38 | + </p> |
| 39 | + <p>Since the Stylesheets are built against the Guidelines, there needs to be a (more or less) up-to-date copy of the Guidelines in the Stylesheet repository. This copy of the Guidelines is a file called “p5subset.xml” and it is stored in the source/ directory. Building the Guidelines in the TEI repository does <hi rend="italics">not</hi> put a new copy of p5subset.xml into the Stylesheets/source/ directory. In order to keep the version of the p5subset.xml in the Stylesheets repository up to date, that file is updated monthly by Council members. |
38 | 40 | </p> |
39 | 41 | <div> |
40 | 42 | <head>Step-by-Step Instructions:</head> |
|
50 | 52 | <item n="2.2.1.2">change to the TEI/P5 directory <code>cd [relative path to TEIC/TEI/ directory]/P5</code> |
51 | 53 | </item> |
52 | 54 | <item n="2.2.1.3">run <code>make clean test</code>. The <code>clean</code> command is to clean your repository of any previously generated files</item> |
53 | | - <!--<item>after you finish the steps below, don’t forget to clean your directory |
54 | | - with <code>make clean</code> to make sure that files generated while running |
55 | | - the test are removed again</item>--> |
56 | 55 | </list> |
57 | 56 | </item> |
58 | 57 | </list> |
|
90 | 89 | the case, read the error message carefully and see if you can figure out what's |
91 | 90 | failing (and reach out to Council members for help). See <ref |
92 | 91 | target="#troubleshooting">Troubleshooting</ref>, below for an example failure of |
93 | | - the ant process and a simple fix.</item> |
| 92 | + the <code>ant</code> process and a simple fix.</item> |
94 | 93 | <item n="4.3"><p>In the case of a diff error, examine the differences generated. If the |
95 | 94 | differences are what you would expect given the change in P5 (which is by far |
96 | 95 | the most common case), just copy the output file to be the new expected results |
|
165 | 164 | [exec] expect: /invalidInstances/testAttValQuantInvalidInstance.xml:77:345: error: element "att_quant:test" missing required attribute "req_2??"<lb/> |
166 | 165 | </eg> |
167 | 166 | </item> |
168 | | - <item n="4.5">To resolve this error, simply run the command below and re-attempt running Test2/ (step 3.2): |
| 167 | + <item n="4.5">To resolve this error, simply run the command below and re-attempt running <code>ant test</code> (step 3.3): |
169 | 168 | <code>export LC_ALL=C.UTF-8; export LANG=C.UTF-8</code></item> |
170 | 169 | </list> |
171 | 170 | </item> |
| 171 | + <item n="4.6">When you solve a "diff" error, re-attempt running <code>ant test</code> again until the build is successful (returns no errors).</item> |
172 | 172 | <item n="5">After all the errors have been fixed in Test2/, move on to Test/. <hi rend="bold">Note:</hi> Step 6 is an alternative approach for Test/.<list> |
173 | 173 | <item n="5.1">switch to the main directory (<code>cd ../Test</code> will do, if you are still in |
174 | 174 | <code>Test2/</code> from previous step)</item> |
175 | 175 | <item n="5.2">run either <code>make</code> or <code>time make</code> [See <ref |
176 | 176 | target="#addendum">Addendum</ref>, below, for using the <code>–jobs</code> |
177 | | - switch to make <code>make</code> run faster.]</item> |
| 177 | + switch for <code>make</code> to run faster.]</item> |
178 | 178 | <item n="5.3">check the errors (the make file stops after each error). <hi rend="bold">Note:</hi> If there is no error, the process is complete.</item> |
179 | 179 | <item n="5.4">When there is an error, you will find a diff of the relevant file from the |
180 | 180 | <code>actual-results/</code> folder and the <code>expected-results/</code> |
|
0 commit comments