From f6b381be2976f6675d3d90fc2b82bd992e1bcc48 Mon Sep 17 00:00:00 2001 From: raffazizzi Date: Tue, 21 Nov 2023 14:57:41 -0500 Subject: [PATCH] cleaned up --- TCW/anyXMLproposal.html | 319 ----------- TCW/howtoChain-fr.html | 21 - TCW/howtoChain.html | 18 - TCW/howtoGenerate-fr.html | 18 - TCW/howtoGenerate.html | 18 - TCW/index.html | 20 +- TCW/pureODDtutorial.html | 20 - TCW/purifyDoc.html | 20 - TCW/purifyDoc_static.html | 133 ----- TCW/tcw20.html | 962 ---------------------------------- TCW/tcw22.html | 494 ----------------- TCW/tcw24.html | 349 ------------ TCW/tcw27.html | 87 --- TCW/tcw29.html | 162 ------ TCW/tcw30.html | 104 ---- TCW/testing_and_building.html | 131 ----- index.html | 4 +- 17 files changed, 11 insertions(+), 2869 deletions(-) delete mode 100644 TCW/anyXMLproposal.html delete mode 100644 TCW/howtoChain-fr.html delete mode 100644 TCW/howtoChain.html delete mode 100644 TCW/howtoGenerate-fr.html delete mode 100644 TCW/howtoGenerate.html delete mode 100644 TCW/pureODDtutorial.html delete mode 100644 TCW/purifyDoc.html delete mode 100644 TCW/purifyDoc_static.html delete mode 100644 TCW/tcw20.html delete mode 100644 TCW/tcw22.html delete mode 100644 TCW/tcw24.html delete mode 100644 TCW/tcw27.html delete mode 100644 TCW/tcw29.html delete mode 100644 TCW/tcw30.html delete mode 100644 TCW/testing_and_building.html diff --git a/TCW/anyXMLproposal.html b/TCW/anyXMLproposal.html deleted file mode 100644 index 9ea6750..0000000 --- a/TCW/anyXMLproposal.html +++ /dev/null @@ -1,319 +0,0 @@ - - - - - - ANY XML and what should replace it - Lou Burnard - - - Circulated to TEI Council for discussion in Vienna - - - No source - - - - - - - In an attempt to progress issue - 1173, I have defined a new element anyElement which is intended to - make a bit more transparent the currently rather obscure working of the macro - macro.anyXML. Think of it as a little piece of pure ODD we did not - finish. You can see its elementSpec here, but of course it doesn't do anything yet since the stylesheets have yet - to be modified to take any notice of it. - In the rest of this note, I will try to summarize how I plan to change elements which - currently make use of macro.anyXML. There are five (or six) of them: - constraint, content, egXML, xenoData, - macro.schemaPattern and of course macro.anyXML itself. - This macro is declared in ST, but redefined in the Exemplar ODDS for tei_AllPlus, tei_math, and - tei_svg, on which see further below. - - - constraint - - - Current content model - Proposed content model - - - - - - - - - - - - - - - - - - - - - - - - - - We simply replace the macroRef here with an elementRef. We could - require that constraints be expressed using the ISO Schematron namespace: - anyElement - include="http://purl.oclc.org/dsdl/schematron" But that - would close the door to constraints expressed in any other schema language, - which might not be such a good thing (and would invalidate an existing example) - - - - - - content - - - Current content model - Proposed content model - - - - - - - - - - - - - - - - - - - - - - - Since anyElement and textNode are already - members of model.contentPart, all that is needed here is to remove the - macroRef. It would be nice to be able to add the constraint that elements - appearing here should come from the RelaxNG namespace, but there is no obvious - way of doing this without introducing an ambiguity. - - - - - - egXML - - - Current content model - Proposed content model - - - - - - - - - - - - - - - - - - - - - - - - - - We can do better here, by requiring that the content be from the - egXML namespace - - - - - xenoData - - - Current content model - Proposed content model - - - - - - - - - - - - - - - - - - - - - - - - - - Again, we can do better by excluding TEI namespaced elements from - the content. Note that the original definition relied on repetition inherent in - the macro. - - - - - macro.schemaPattern - - - Current content model - Proposed content model - - - - - - - - - - - - - - - - - - - - This macro is used only as part of the content model for - datatype, in order to permit continued use of relaxng data - definitions. The redefinition above makes this explicit. - - - - - macro.anyXML itself - - - Current content model - Proposed content model - - - - - - - - - - egXML - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The part of the original definition precluding a - self-nestingteix:egXML has to be implemented with a schematron - constraint if we want to include it. - - - - - - Exemplars - As noted above, three of the supplied TEI Exemplars redefine - macro.anyXML. In each case, the redefinition is needed to exclude - elements from specific namespaces. In teiAllPlus, the - elementRef needs to be <anyElement - except="http://www.tei-c.org/ns/1.0 http://www.w3.org/1998/Math/MathML - http://www.w3.org/2000/svg"/> . Similarly, in tei_math, the - exclusion list needs to mention http://www.w3.org/1998/Math/MathML and - in tei_svg, http://www.w3.org/2000/svg - Implementation - Here's a sketch of a template that might be used to replace anyElement with suitable RELAXNG content: - - - - - - - - - - - - - - - - - - - - - - - - - - - It's not clear where exactly this or something like it should fit inside the current ODD processing stylesheets. - - - - diff --git a/TCW/howtoChain-fr.html b/TCW/howtoChain-fr.html deleted file mode 100644 index 9e28ba6..0000000 --- a/TCW/howtoChain-fr.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - - ODD Chaining for Beginners - - - - - diff --git a/TCW/howtoChain.html b/TCW/howtoChain.html deleted file mode 100644 index 9db3dba..0000000 --- a/TCW/howtoChain.html +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - - ODD Chaining for Beginners - - - - - diff --git a/TCW/howtoGenerate-fr.html b/TCW/howtoGenerate-fr.html deleted file mode 100644 index a7742df..0000000 --- a/TCW/howtoGenerate-fr.html +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - - Comment générer automatiquement un ODD - - - - - diff --git a/TCW/howtoGenerate.html b/TCW/howtoGenerate.html deleted file mode 100644 index 7a38033..0000000 --- a/TCW/howtoGenerate.html +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - - How to make an ODD automagically - - - - - diff --git a/TCW/index.html b/TCW/index.html index 0d84614..86d704d 100644 --- a/TCW/index.html +++ b/TCW/index.html @@ -7,16 +7,16 @@
diff --git a/TCW/pureODDtutorial.html b/TCW/pureODDtutorial.html deleted file mode 100644 index b4dba90..0000000 --- a/TCW/pureODDtutorial.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - - - - Introducing Pure ODD - - - - - diff --git a/TCW/purifyDoc.html b/TCW/purifyDoc.html deleted file mode 100644 index bdb63ba..0000000 --- a/TCW/purifyDoc.html +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - - - - How to Update your ODD - - - - - diff --git a/TCW/purifyDoc_static.html b/TCW/purifyDoc_static.html deleted file mode 100644 index 11a68b2..0000000 --- a/TCW/purifyDoc_static.html +++ /dev/null @@ -1,133 +0,0 @@ -How to Update your ODD

(unknown project)

How to Update your ODD

Table of contents

1. What is this for?

This little guide is intended to simplify and clarify the task of maintaining or updating an existing TEI customization (an ODD), in particular an ODD which was written before release 3.0 of TEI P5. That release introduced several new features intended to remove the system's reliance on other schema languages. These changes (colloquially known as ‘purification’ because their motivation was to ensure that all aspects of a TEI specification should be encoded using TEI and nothing else 1) affect only the way that the content model of an element or the datatype of an attribute are defined, but for completeness we have included reminders about some other customization features that you may wish to review.

2. It ain't broke: why fix it?

Since release 2.0 it has been possible to tie any ODD file to a particular release of the Guidelines. If you know approximately the date of the release of TEI P5 against which your ODD was first compiled, you can use the source attribute to ensure that it continues to use that source. This has the obvious advantage that you don't have to do any work to maintain it, but some equally obvious disadvantages:

Nothing in digital form is ever really finished. It's more than likely that the requirements of your project will have changed a little since your ODD was first designed. It's almost inevitable that as your project evolves, you'll have come across things you'd do differently if you could start all over again. Reviewing your ODD is a very good way of thinking about doing that.

3. Good things to review

Here's little checklist of things you might want to review in the light of experience:

And yes, it's quite likely that as a result of this review, you may well need to change all your data as well as your schema. But that's a simple matter of XSLT programming ...

4. Content Model Revision

In days of yore, (i.e. releases P1 to P3 inclusive) TEI Content Models were expressed in the SGML language. The first XML release TEI P4, and all releases of P5 prior to 3.0 used the ISO standard RELAXNG language for this purpose. But from the start, a design goal of the TEI was to define an encoding scheme independent of any implementation metalanguage. The TEI has always used its own ‘ODD’language to define components which are then processed to produce documentation in a variety of formats (HTML, PDF, ePub etc.) and schemas in a number of different languages (RELAXNG, W3C Schema, and XML DTD). At release 3.0 this principle was extended to the definition of content models, which previously had been expressed using the RELAXNG language, but which are now expressed using some special purpose TEI elements2.

If your customization changed the content model of any element, it will have done so using expressions in RELAXNG, typically using a <rng:ref> element to provide the name of a pattern. For example, suppose your customization defined a new element with a content model of macro.phraseSeq. In the <elementSpec> defining your new element, there will be a <content> element containing something like <rng:ref name="macro.phraseSeq"/>. To keep in step with the current TEI P5 release, you need to change this RELAXNG content to its equivalent in the ODD language which is <macroRef key="macro.phraseSeq"/>.

In the ODD language, references to different kinds of object (elements, classes, macros, etc.) in a content model are represented by different element types, specifically <elementRef>, <classRef>, <macroRef>.Hence, a RELAXNG content model in the form <rng:ref name="x"> will become classRef key="x"/ if x names a class, elementRef key="x" if it names an element, and macroRef key="x" if it names a macro.

Content models can of course be much more complicated. If your RELAXNG model uses an alternation or a sequence of components, you will need to use one of the ODD elements <alternate> and <sequence> to wrap them rather than the RELAXNG (semi)equivalents rng:choice and rng:group respectively. For example, this RELAXNG model says that a <foo> can contain either a <bar> or a <baz>:
<rng:choice> - <rng:ref name="bar"/> - <rng:ref name="baz"/> -</rng:choice>
Its equivalent in pure ODD would be
<alternate> - <elementRef key="bar"/> - <elementRef key="baz"/> -</alternate>
If some components of your content model are optional or repeatable, you will have used the RELAXNG elements <rng:oneOrMore> or rng:zeroOrMore. In ODD optionality and repeatability are expressed using attributes minOccurs and maxOccurs, which can be supplied for any of the elements discussed so far. For example, a RELAXNG content model such as
<rng:oneOrMore> - <rng:choice> -  <rng:ref name="bar"/> -  <rng:ref name="baz"/> - </rng:choice> -</rng:oneOrMore>
has the following equivalent in pure ODD
<alternate minOccurs="1" - maxOccurs="unbounded"> - <elementRef key="bar"/> - <elementRef key="baz"/> -</alternate>

An empty element is indicated in the RELAXNG language by a special pattern called empty. In the ODD language, however, we indicate that an element has no content by supplying an empty <content> element in its specification.

The ODD language also provides a few more special-purpose component elements for content models: <textNode><valList> and (probably) <anyElement>.

The <textNode> element is provided as a replacement for the built-in RELAXNG pattern text. There are no restrictions on where it may be placed in an ODD content model, although existing schema languages mostly permit it to appear only in mixed content models like the following:
<alternate minOccurs="0" - maxOccurs="unbounded"> - <textNode/> - <elementRef key="foo"/> -</alternate>

The RELAXNG language allows a number of other components within a content model, some of which are difficult to convert, but few of which are likely to appear in a pre-existing TEI ODD. If your ODD used the RELAXNG element <rng:value> to specify content explicitly, this must be expressed in an ODD as a <valItem> within a <valList>. If your ODD used the RELAXNG element <rng:element> to specify that any element is permitted at this point in a content model, you can do something similar with the ODD <anyElement> element. In general, however, the presence of any of the following in your old content model will require manual intervention: rng:anyName rng:attribute rng:data rng:element rng:except rng:name nsName rng:param rng:value

Here are some example <content> elements taken from the content models of existing TEI elements:

RELAXNG SpecificationODD equivalent
<content> - <rng:oneOrMore> -  <rng:ref name="cell"/> - </rng:oneOrMore> -</content>
<content> - <elementRef key="cell" -  minOccurs="1" -  maxOccurs="unbounded"/> -</content>
<content> - <rng:zeroOrMore> -  <rng:choice> -   <rng:text/> -   <rng:ref name="model.limitedPhrase"/> -   <rng:ref name="model.global"/> -  </rng:choice> - </rng:zeroOrMore> -</content>
<content> - <alternate minOccurs="0" -  maxOccurs="unbounded"> -  <textNode/> -  <classRef key="model.limitedPhrase"/> -  <classRef key="model.global"/> - </alternate> -</content>
<content> - <rng:group> -  <rng:zeroOrMore> -   <rng:ref name="analytic"/> -  </rng:zeroOrMore> -  <rng:oneOrMore> -   <rng:ref name="monogr"/> -   <rng:zeroOrMore> -    <rng:ref name="series"/> -   </rng:zeroOrMore> -  </rng:oneOrMore> -  <rng:zeroOrMore> -   <rng:choice> -    <rng:ref name="model.noteLike"/> -    <rng:ref name="model.ptrLike"/> -    <rng:ref name="relatedItem"/> -    <rng:ref name="citedRange"/> -   </rng:choice> -  </rng:zeroOrMore> - </rng:group> -</content>
<content> - <sequence> -  <elementRef key="analytic" -   minOccurs="0" -   maxOccurs="unbounded"/> -  <sequence minOccurs="1" -   maxOccurs="unbounded"> -   <elementRef key="monogr"/> -   <elementRef key="series" -    minOccurs="0" -    maxOccurs="unbounded"/> -  </sequence> -  <alternate minOccurs="0" -   maxOccurs="unbounded"> -   <classRef key="model.noteLike"/> -   <classRef key="model.ptrLike"/> -   <elementRef key="relatedItem"/> -   <elementRef key="citedRange"/> -  </alternate> - </sequence> -</content>

5. Attribute values and datatypes

As noted above, you may wish to change your existing ODD to be more precise in the way that attribute values are specified. If you decide to introduce a <valList> (senmi-closed or closed) to constrain the possible values of an attribute you will also need to change its <datatype> to reference teidata.enumerated.

If the <datatype> element appears in your ODD already, you will need to change it to use a <dataRef> element pointing to one of the predefined teidata datatype specifications. A set of predefined data specifications using RELAXNG has been retained for compatibility reasons, but these will probably be withdrawn by the end of 2017.

Proceed as follows:

Here are some example <content> elements taken from the data specifications used by some existing TEI datatypes :

RELAXNG SpecificationODD equivalent
<content> - <rng:data type="NCName"/> -</content>
<content> - <dataRef name="NCName"/> -</content>
<content> - <rng:data type="nonNegativeInteger"> -  <rng:param name="maxInclusive">100</rng:param> - </rng:data> -</content>
<content> - <dataRef name="nonNegativeInteger" -  restriction="[0-9][0-9]?"/> -</content>
<content> - <rng:choice> -  <rng:data type="float"> -   <rng:param name="minExclusive">0</rng:param> -  </rng:data> -  <rng:value>regular</rng:value> -  <rng:value>irregular</rng:value> -  <rng:value>unknown</rng:value> - </rng:choice> -</content>
<content> - <alternate> -  <dataRef name="float"/> -  <valList> -   <valItem ident="regular"/> -   <valItem ident="irregular"/> -   <valItem ident="unknown"/> -  </valList> - </alternate> -</content>
<content> - <choice> -  <rng:value>high</rng:value> -  <rng:value>medium</rng:value> -  <rng:value>low</rng:value> -  <rng:value>unknown</rng:value> - </choice> -</content>
<content> - <valList type="closed"> -  <valItem ident="high"/> -  <valItem ident="medium"/> -  <valItem ident="low"/> -  <valItem ident="unknown"/> - </valList> -</content>

6. My head hurts: where's the script?

Yes, there is a script or two you can experiment with if you find this all too daunting. They were used to transform the whole of the pre-3.0 TEI Guideline specifications semi-automatically. They deal with 99% of the situations you are likely to encounter, but they're not guaranteed ! You can find them on Github at https://github.com/TEIC/TEI/tree/dev/P5/Scripts: use them in good health, but at your own risk.

Don't hesitate to share your experience, good or bad, on the TEI discussion list, by raising a ticket on Github, or by contributing to the TEI wiki. The TEI is a community effort!

Notes
2
The authoritative source of information on these is of course chapter 22 of the Guidelines Documentation Elements. In any disagreement between what is stated there and what is suggested here, the former is correct.
Home 
Lou Burnard. - Date: 2016-10-06
\ No newline at end of file diff --git a/TCW/tcw20.html b/TCW/tcw20.html deleted file mode 100644 index b7a76d6..0000000 --- a/TCW/tcw20.html +++ /dev/null @@ -1,962 +0,0 @@ - - - - - - How to edit the TEI Guidelines - Lou Burnard - - - Text Encoding Initiative - 2011 - - - All my own work - - - - Adding guidance on how to provide supporting explanation with remarks and with paragraphs within exempla. - Changed link to TCW 24. - Revised explanation of how to work in repo branches other than dev branch. - Linked to schema that actually exists, and tweaked to handle the fallout. - Adding documentation on how to create or edit an Appendix to the Guidelines. - Adding more documentation to clarify where some processing instructions in the Guidelines are actually processed. - Updates to account for new Jenkins server subdomains. - Updates to account for the change from master to dev branch on GitHub. - Updates to account for the shift from SF SVN to GitHub. - Added exhortation to include sufficient linebreaks in examples, - to avoid distorted page rendering in the Guidelines HTML output. - Added clarification about how to XInclude a new spec file. - Some clarifications, including not to use valDesc. - Made more explicit that you have to update @versionDate when editing the content of an element that it's located on. - When closing a ticket, add the URL of the revision number. Also replaced all "SVN" with "Subversion" when referring to the software. - Copyediting and clarified how to do citations per https://sourceforge.net/p/tei/bugs/527/ . - Full path to schema for validation - We should use egXML@source instead of egXML@corresp per Sebastian. - Clarified svn commit instructions. - Clarified what to include in a specList. Removed info that duplicates tcw24. Some light copyediting. - Revised instructions for creating a new element to take account of the switch to XInclude from entities. - Revised Schematron section based on feedback from KH. - Added a section on adding Schematron constraints. - Removed sections redundant with new TCW24 and redirected a link there. - Added instructions on when you can edit translations of specs. - 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. - Created new section on good encoding practice, which includes info on @xml:id and @target and new note about using ptr instead of ref. - Removed "building a release" section and replaced with link to tcw22. - updated publicationStmt; added steps on updating latest download and creating news item in SourceForge - correction by David Sewell per SR request - started first draft - - - - - This document is intended to set out the way things are - currently managed in the - editing of the TEI Guidelines. General notes on the rationale - for this state -- why it is the way it is -- may be added here - later. The intention is to provide information for Council - members wishing to contribute actively to the continued - development and maintenance of the text of the Guidelines. - - Organization of the Guidelines chapters - It cannot have escaped your notice that each chapter (almost) of the Guidelines defines a - distinct module. In theory at least, each chapter is organised in more or less the same - way: - it begins with a paragraph explaining what the module is for, and containing a lot - of links to the individual subsections it contains; - each subsection introduces a (small) group of elements, usually beginning with a - specList, which will typically list all the elements discussed within a - given section, listed in whatever order makes sense for the context, but not necessary - all possible child elements for a given element; - each element is then introduced in turn, usually including an appropriate usage - example (on examples, see further ); - a specGrp for each group of elements defined may be given at the end of - each section; - a specGrp for the whole module is given at the end of the chapter: it - includes the other specifications either directly (by means XIncludes) or - indirectly (by means of a specGrpRef pointing to a preceding - specGrp). - -The only chapters not organised in this way are those which do not -introduce or define particular modules. - - - Organization of the specifications - Each element, class, and macro defined in the Guidelines is - declared within its own XML file, - containing an elementSpec, classSpec, or macroSpec as - appropriate. These files are in the directory - Source/Specs. For example, the file - Source/Specs/abbr.xml contains the element spec for the abbr element. - Note that the elements for the major components of the spec each have a versionDate. - If editing the content of the element, you must remember to update the value of this - attribute in order to allow for detection of translations (stored in the same file) that need - updating. As a general rule, don't update a translation for any language of which you are not - a native speaker. If you feel confident enough to adjust the translation, leave the - versionDate attribute unchanged on the translation in order to ensure the translation - will be reviewed eventually. - Each chapter of the Guidelines is stored in a file called - Source/Guidelines/xx/YY-name.xml where xx is the language (currently only en or - fr), YY is the two letter identifier for each chapter (see ) - and name is the name of the module being defined by that chapter. - The file Source/guidelines-xx.xml (where xx is either en or fr) is the - driver file for the whole shebang. It contains XInclude elements - for each of the chapters making up the Guidelines. - Hence, to add a new element (say saintName) you - might proceed as follows: - Write a new file saintName.xml containing an elementSpec - for your new element and add it to the Specs folder. Look at other specifications - to see which ODD elements - to use. Note that we do not use valDesc at this time, instead using only a datatype. - Edit the source of the relevant chapter (presumably - ND-namesdates.xml in this example) to include a documentation of the element. Use a - specList to reference the description from your new spec within the body of - the text, like this: - - This module also defines the following canonical element: - - - - -and follow up with some discussion of usage. - - - Also in the relevant chapter, make sure you include an XInclude instruction to bring the specification - file for your element into the Guidelines source. Normally you would add it to an existing specGrp - element somewhere in the chapter source which already contains similar links: - - <specGrp xml:id="DNDPER" n="Personal and organizational names"> - <include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/orgName.xml"/> - <include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/saintName.xml"/> - [...] - </specGrp> - - - - - - - - - -Processing Instructions - In some places in the Guidelines source code, you will notice processing instructions which look like this: - - - <?insert totalElements?> - - -These processing instructions are replaced during the Guidelines build process by generated content. (That processing -takes place in the XSL module P5/Utilities/expand.xsl.) In the -case of the example above, the total number of elements defined in the current version of the Guidelines is -calculated and inserted. This is a list of the processing instructions currently in use, and what they are replaced -by: - - - <?insert tab-content-models?> - Inserts a generated table of content models into the ST chapter (not likely to be used elsewhere) - <?insert totalElements?> - Inserts a count of the total number of elements defined in the current version - <?insert version?> - Inserts the current version number of the TEI release - - -If you are writing a Guidelines section that can use one of these variables, feel free to insert the appropriate -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. - - - - - Style Notes - - General - See the Style - Guide for Editing the TEI Guidelines, - which attempts to state preferred practice on vexed issues - issues about spelling, punctuation, etc. The goal of these rules is to avoid - inconsistency, and also (wherever possible) to avoid producing text which is markedly - either British or American English. - - - - Examples - The purpose of an example is to illustrate a specific element or feature. Do not - include irrelevant encoding which does not contribute to this primary goal. If such - encoding is unavoidable (eg to make your example valid), then it must be explained in - the supporting text. You may provide supporting explanation for an example in one of two ways: - in a p element within the exemplum, or in a remarks element. - A p element within an exemplum should only be used for an explanation specific to that particular example. - A remarks element should provide explanation for the usage of an element or attribute and need not be tied to a specific example, - though it may refer to one. Be careful when writing a supporting explanation not to refer to an example as - above or below the explanation, or to indicate the first or second example in a series since - the rendering of the Guidelines could change and examples could change order or position as new ones are added. - Wherever possible, choose your examples from real documents and provide bibliographic - citations for them, either: - - in a note element, with a place whose value is bottom or - foot, following the egXML (if the citation is only a URL in a - ptr) - in a full bibliographic citation (with or without a URL in ptr) in - the file BIB-Bibliography.xml - - Use the source attribute on the egXML element to link an example to its source. Note - that the xml:lang attribute is mandatory on exemplum: this is to - ensure that the ODD processor knows which examples to choose in a given context. - All examples should be valid against a modified TEI schema in which any element can act - as a root element; this validity is checked during the build process. - When you have added or edited examples, always check in the following Jenkins build - that they are displaying correctly. In particular, note that if your examples include - long lines without linebreaks, the result can be a horizontally-scrolling page and a - broken table layout in the reference page. If you see this in the output, you can fix it - by adding hard-coded linebreaks at suitable points in the example code. - - - - Good encoding practice - Good encoding practice will ensure not only valid but - also highly functional Guidelines. - When referencing figures and to other sections of the - Guidelines, use ptr, not ref, to ensure - that the title and number of the referenced item is - automatically inserted when the Guidelines are compiled. - The build process validates cross-references. - Since the Guidelines is compiled into a single XML document - at build time, IDs must be unique across the text and the - examples. Consequently, any xml:id attribute - values appearing in your examples must be unique within the - text of the whole of the Guidelines. Furthermore, any - target (etc.) values which do not point to - anything in the source will be flagged with a warning during - the build process. - - - - Making a change to the Guidelines - - Most changes to the Guidelines are the result of a bug or feature request - ticket on GitHub. Once a ticket is assigned to you, and you're sure there - is agreement to proceed with the change, follow the steps below. - - - If you don't have a local clone of the git repo, go to the GitHub site and clone the repository following the instructions there. It's usually something like git clone https://github.com/TEIC/TEI.git TEI - If you have already checked out a copy, make sure to update it (git pull) before - you make any changes in it. - Make sure you are on the dev branch (we do not make direct changes to the master branch): git checkout dev - 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 - contain xml-model processing instructions linking them to the latest version - of the NVDL file used for validation of the P5 source. - If you have a locally installed P5 build environment, make sure you can still build, - and that the examples are still valid. You can set up a Docker-based build environment - by following the instructions in . If you do not have a build - environment nor the means to set one up, just use git to push your updated version to - GitHub and wait for our two Jenkins Continuous Integration servers ( and ) to assess your work. - Check in your changes: - - If the file is new, add it to the git repository: git add filename.xml - - - Commit your changes: git commit -m "Your commit message" filename.xml Be sure to add a detailed commit message which includes a link to the git issue ticket which prompted the change. - Push the change to the git repository: git push origin dev - Make a note of the revision hash when git receives your change. - 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. - - Error messages may appear at any stage. Please do not leave the source in an invalid - state (it makes life unnecessarily difficult for others). If you cannot immediately fix a - validity error, revert your change while you think about it. - 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 git rebase, 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 Atalassian tutorial on merging vs. rebasing. 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 @TEIC/tei-technical-council. 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. - - 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: - - - 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. - The required packages on the Jenkins servers tend to be updated regularly, and we're watching them to make sure they work properly. - Jenkins attempts to let you know by email if there's a problem, and provides useful debugging tools. - - - 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: - - - 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. - 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 Parsed Console Output on the left menu. You'll see links to Errors and Warnings; 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. - 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. - 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. - - - Error messages appearing during the make test phase (the TEIP5-Test job on Jenkins) usually indicate that - your changes are in conflict with the Birnbaum Doctrine, which decrees that changes in the - Guideline schemas should not invalidate existing documents. You may wish to discuss the - specific issue with other Council members. - - - - - Images - - If you use an image in your Guidelines change, you will need to add it to the git repository - in the P5/Images directory. If you have asked for and received permission - from a rights-holder to use the image, include all of the relevant correspondence in a zip - file named the same as the image file (so for an image fred.png, include - permission documents in a file called fred.zip). - - - - - Adding or Editing an Appendix - - The Appendices to the TEI Guidelines mostly constitute lists of features (elements, attributes, classes etc.) which have been automatically harvested from the Guidelines compiled source (p5.xml or p5subset.xml) during the build process. When adding a new appendix of this type, you need to: - - - Create a new APPENDIXTHING.xml file in the TEI/P5/Source/Guidelines/en/ 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 .xml. - - Add a line to TEI/P5/Source/guidelines-en.xml (right near the end of the file) to XInclude your file in the Guidelines. 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. - - If your appendix listing is to be created automatically, edit the appropriate file in the Stylesheets repository (most likely Stylesheets/common/common_tagdocs.xsl) to enable it to generate the list or table (see below). - - 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 Stylesheets/i18n.xml (if they're not already there). - - - - Auto-generated appendix listings will require two things: a TEI divGen element which acts as a trigger to cause the list to be generated, and a Stylesheets template which processes the divGen to create the output. For example, the list of deprecations consists of this DEPRECATIONS.xml file: - - - - - Deprecations - - About the Deprecation Appendix - This appendix gives you a list of all items (elements, - attributes, attribute values, datatypes etc.) which are deprecated - in this revision of the TEI Guidelines (revision <?insert -revision?> of TEI P5 <?insert version?>). - - - - - - Note that there are two kinds of auto-generated content here: first, the two processing instructions - <?insert revision?> and - <?insert version?>, which are self-explanatory and can simply be used, and - <divGen type="deprecationcat"/>, which was created specifically for this appendix file, and for which processing had to be explicitly written. - - If you now look at Stylesheets/common/common_tagdocs.xsl, you'll find this template: - - - - <xsl:template match="tei:divGen[@type = 'deprecationcat']"> - <xsl:element namespace="{$outputNS}" name="{$tableName}"> - <xsl:attribute name="{$rendName}"> - <xsl:text>deprecationcat</xsl:text> - </xsl:attribute> - <!-- .. --> - </xsl:element> - </xsl:template> - - - This template creates a table in whatever the target output format is, listing the deprecations. Note that the table headings are created like this: - - - - <xsl:element namespace="{$outputNS}" name="{$cellName}"> - <xsl:element namespace="{$outputNS}" name="{$hiName}"> - <xsl:attribute name="{$rendName}"> - <xsl:text>label</xsl:text> - </xsl:attribute> - <xsl:attribute name="{$langAttributeName}"> - <xsl:value-of select="$documentationLanguage"/> - </xsl:attribute> - <xsl:sequence select="tei:i18n('Identifier')"/> - </xsl:element> - </xsl:element> - - - - where the keyword Identifier is used to look up the appropriate language translation in the Stylesheets/i18n.xml 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 Stylesheets/i18n.xml like this: - - - - - Identifier - Identifier - - - - and if you are competent to add the equivalent translations in any of the Guidelines languages, you can add them alongside the English version: - - - - Description - Description - Beschreibung - Description - Descrizione - - - 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. - - Of course, a simple manual appendix consisting of some explanatory prose can be created simply by adding the APPENDIXTHING.xml file and XIncluding it in guidelines-en.xml, with no Stylesheets changes required. - - - - - - - - - Adding Schematron constraints to specifications - - The TEI ODD system is primarily concerned with generating schemas in the form of RelaxNG or XML Schema. - However, there are often circumstances in which you want to apply constraints to elements and attributes which cannot easily be captured by - normal XML schemas. For instance, you might want to apply a co-occurrence constraint on some attributes. The targetLang attribute - is a good example. targetLang is an optional attribute which “specifies the language of the content to be found - at the destination referenced by target, using a language tag generated according to - BCP 47.” Obviously, there is no point in using targetLang - if you're not also using target. However, many such co-occurrence constraints are difficult to express - in RelaxNG schemas, and may not survive conversion to other schema formats such as XML Schema or DTD. - - For this reason, we often use ISO Schematron to express constraints like this. If you look in att.pointing.xml, where the targetLang -attribute is defined, you'll find this constraint, inside the attDef for targetLang: - - - - - - @targetLang can only be used if - @target is specified. - - - - - - - This Schematron rule is an assertion that if targetLang is used, target should also be present. constraintSpec -has an attribute scheme (normally set to isoschematron). Inside constraintSpec, constraintss hold elements in the Schematron namespace. The Schematron rule element establishes the TEI node to be tested with its context attribute. The rule holds one or more elements, either assert or report that define conditions to be checked in a test attribute. Here we see an assert element, -which has test attributes. The test attribute value is always an XPath expression; if the XPath tests false, the assertion will be triggered, and its -contents will appear on the console when you build or validate. There is also a report element which is similar, but which triggers when true rather than when false, -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. -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 -processes that take place using other schemas. Notice, finally, the role attribute, set in our example on the rule element. This attribute defines a level of severity for the test if its test passes with a Boolean true result in a report, or if the test fails with a Boolean false result in a assert. Values for role 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 role attribute is set, the default severity in Schematron is "error". The role attribute can be applied either to the Schematron rule element or to its assert and report children, which can have differing levels of severity. For a full introduction to Schematron, see the Schematron website. - - constraintSpec can appear as a child of attDef, classSpec, elementSpec, macroSpec, and schemaSpec. -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 (date, birth etc.) and -the calendar attribute. calendar indicates the system or calendar to which the date represented by the content of this element belongs. In other -words, calendar should only be used if the dating element has textual content. This makes sense (assuming that calendar points at a valid calendar element): - - - January, 1622 - - - - whereas this is not: - - - - - - - because the date element has no textual content to which the calendar attribute could apply. We're going to express this in the form of a Schematron -constraint, along the lines of the one we've examined above. First, we open the att.datable.xml file, and find the attDef element which defines calendar. -We can add the constraintSpec element immediately after the datatype element, like this: - - - - - - - - @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. - - - - - - - (Obviously, by the time you're reading this, the constraintSpec is already in the TEI source, so you'll see it there.) If the Schematron namespace is not -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 classSpec root element: -xmlns:sch="http://purl.oclc.org/dsdl/schematron". Then we commit our changes, and let the TEI build process build all the products, and make sure that -we didn't get anything wrong. - - When writing Schematron constraints for the Guidelines, bear these points in mind: - - 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. - Break up the message up into fairly short lines, so that it's easy to read when it appears in the build log. - Use the name element in place of the name of the context element. This will be helpful for future processing needs. - Refer to attributes using the "@" prefix, rather than quotation marks or plain names (as above). - - - - - 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 -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 -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 -as we expect. - - 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 calendar and some textual content, as well as an -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 -all, of course; that comes later.) - - If you look at trunk/P5/Test, 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 -our tests to one of these files. The question is which one? We'll add it to the basic test file, which is testbasic.xml; this is tested against schemas generated from testbasic.odd, -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 -calendar attribute to one of those. Let's choose the date of 1685 on a dictionary entry sense: - - - - - 1685 - - pamplemousse - - - - - We could go to the trouble of adding calendarDesc and calendar to the header of the file so we can point to a calendar element in the same document, -but since calendar is a data.pointer, we can point to an external source of calendar information. - - We also want to add, somewhere, a date element which has no textual content and no calendar attribute. We might as well do this in the header, -by adding a simple revisionDesc element, which gives us the added bonus of being able to describe our change: - - - - <date when="2012-09-06"/>MDH: Added @calendar to one date, and the date - element in here, for testing a new Schematron constraint. - - - - - Now we can commit our change, and see if the build of TEIP5-Test completes successfully on our Jenkins servers. - - 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. -In order to do that, we have to use the "detest" system. In trunk/P5/Test, you'll find the following files: - - - expected-results/detest.log - detest.odd - detest.xml - - - detest.odd and detest.xml are test files like the ones we've seen above, but the purpose of the detest files is to introduce deliberate errors and make sure that the testing process throws up the expected error results. What happens is basically this: - - - Schemas are built from detest.odd (including a Schematron schema). - The file detest.xml is validated against those schemas. - Resulting error messages are collected in a file called detest.log (in the Test directory). - That file is compared with the detest.log file in the expected-results subdirectory. - If they are not identical, the test build fails. - - - So what we need to do is to add some new markup to detest.xml 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 detest.log 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: - - - Add our new test to detest.xml. - Commit the change to the git repository. - Let Jenkins run the build (which should fail). - Examine the resulting detest.log on Jenkins, and copy it to our local expected-results/detest.log. - Commit that change to the repository. - Let Jenkins build again, and make sure that the build completes successfully. - - - We'll add this div to the detest.xml file: - - - - - Added by MDH. This tests the Schematron constraint that any element with - @calendar must have some textual content. - - - - - 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: - - - https://jenkins.tei-c.org/job/TEIP5-Test-dev/ws/P5/Test/ - https://jenkins2.tei-c.org/job/TEIP5-Test-dev/ws/P5/Test/ - - - we'll see a file called detest.log, and if we look inside it, we'll find this bit, generated by our constraint: - - @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) - - This line is obviously missing from expected-results/detest.log, so the build failed when the two files were compared. We can fix that very simply: - - - Download the detest.log file from the TEIP5-Test workspace on the Jenkins server (job/TEIP5-Test/ws/Test/). - Copy its contents into our local file expected-results/detest.log. - Commit this change to git (git commit followed by git push). - Watch Jenkins build P5-Test again, and make sure it completes successfully. - - - - - - - - -Building the release - -Note: the original content of this section has been removed, because a longer document dedicated to - documenting the release process has been created. Please refer to TCW22: Building a TEI Release. - - - - - - - Reference section - - Chapter codes -Following a lengthy debate in the Council as to whether the -two-character codes originally used to identify individual chapters -should be dropped in favour of longer more human-readable names, a -compromise solution was reached in which the two character codes were -retained as prefixes to longer human-readable names. The same -two-character codes are also used to identify the HTML and PDF files -generated during the release process. -The following -table shows the correspondence between the printed organization of the -Guidelines and the corresponding filenames. The order is determined by the -driver file Source/guidelines-xx.xml, from which the -table is derived. - -SectionTitlefilename - -[i]Releases of the TEI Guidelines -TitlePageVerso.xml - -[ii]Dedication -Dedication.xml - -[iii]Preface and Acknowledgments -FM1-IntroductoryNote.xml - -[iv]About These Guidelines -AB-About.xml - -[v]A Gentle Introduction to XML -SG-GentleIntroduction.xml - -[vi]Languages and Character Sets -CH-LanguagesCharacterSets.xml - -[1]The TEI Infrastructure -ST-Infrastructure.xml - -[2]The TEI Header -HD-Header.xml - -[3]Elements Available in All TEI Documents -CO-CoreElements.xml - -[4]Default Text Structure -DS-DefaultTextStructure.xml - -[5]Representation of Non-standard Characters and -GlyphsWD-NonStandardCharacters.xml - - -[6]VerseVE-Verse.xml - - -[7]Performance Texts -DR-PerformanceTexts.xml - -[8]Transcriptions of Speech -TS-TranscriptionsofSpeech.xml - -[9]Dictionaries -DI-PrintDictionaries.xml - -[10]Manuscript Description -MS-ManuscriptDescription.xml - -[11]Representation of Primary Sources -PH-PrimarySources.xml - -[12]Critical Apparatus -TC-CriticalApparatus.xml - -[13]Names, Dates, People, and Places -ND-NamesDates.xml - -[14]Tables, Formulæ, and Graphics -FT-TablesFormulaeGraphics.xml - -[15]Language Corpora -CC-LanguageCorpora.xml - -[16]Linking, Segmentation, and Alignment -SA-LinkingSegmentationAlignment.xml - -[17]Simple Analytic Mechanisms -AI-AnalyticMechanisms.xml - -[18]Feature Structures -FS-FeatureStructures.xml - -[19]Graphs, Networks, and Trees -GD-GraphsNetworksTrees.xml - -[20]Non-hierarchical Structures -NH-Non-hierarchical.xml - -[21]Certainty, Precision, and Responsibility -CE-CertaintyResponsibility.xml - -[22]Documentation Elements -TD-DocumentationElements.xml - -[23]Using the TEI -USE.xml - -[A1]Model Classes -REF-CLASSES-MODEL.xml - -[A2]Attribute Classes -REF-CLASSES-ATTS.xml - -[A3]Elements -REF-ELEMENTS.xml - -[A4]Attributes -REF-ATTRIBUTES.xml - -[A5]Datatypes and Other Macros -REF-MACROS.xml - -[A6]Bibliography -BIB-Bibliography.xml - -[A7]Prefatory Notes -PrefatoryNote.xml - -[A8]Colophon -COL-Colophon.xml - -In most chapters, the two character code is also used as a prefix -for the xml:id values given to each div -element. Note that every div element carries an -xml:id value, whether or not it is actually referenced -explicitly elewhere in the Guidelines. - -Note that files with names beginning REF contain -only divGen elements: their content, which provides the -reference documentation (sections A1 to A5 inclusive), is -automatically generated during the build process. - - - Naming conventions - TEI naming conventions have evolved over time, but remain fairly consistent. - - generic identifiers - An element and attribute identifiers should be a single natural language word in - lowercase if possible. If more than one word is conjoined to form a name, then the - first letter of the second and any subsequent word should be uppercased. Hyphens, - underscores, dots etc are not used within element or attribute names. - class names - Class names are made up three parts: a name, constructed like an element name, - with a prefix and optionally a suffix. The prefix is one of model. or - att. and indicates whether this is a model or an attribute class. The - suffix, if present, is used to indicate subclassing: for example - att.linking.foo is the foo subclass of the attribute - class att.linking - xml:id values - The conventions for these vary somewhat. Most of the older chapters of the - guidelines have consistently constructed identifiers, derived from the individual - section headings. Identifiers must be provided for: - every div, whether or not it is explicitly linked to elsewhere - every bibliographic reference in the BIB-Bibliography.xml file - - - -File release structure - -Currently, the organisation of the /usr/share/xml/tei and -/usr/share/doc/tei-* directories on the TEI web site is -as follows: - -tei -|-- Test -|-- custom -| |-- odd -| |-- schema -| | |-- dtd -| | |-- relaxng -| | `-- xsd -| `-- templates -|-- odd -| |-- Exemplars -| |-- ReleaseNotes -| |-- Source -| | |-- Guidelines -| | | |-- en -| | | | `-- Images -| | | `-- fr -| | | `-- Images -| | |-- Images -| | `-- Specs -| | |-- 18decembre -| | `-- exemples -| |-- Utilities -| `-- webnav -| `-- icons -|-- schema -| |-- dtd -| `-- relaxng -|-- stylesheet -| |-- common -| |-- common2 -| |-- docx -| | |-- from -| | | |-- dynamic -| | | | `-- tests -| | | | `-- xspec -| | | |-- graphics -| | | |-- lists -| | | |-- marginals -| | | |-- maths -| | | |-- paragraphs -| | | |-- pass0 -| | | |-- pass2 -| | | |-- tables -| | | |-- templates -| | | |-- textruns -| | | |-- utils -| | | `-- wordsections -| | |-- misc -| | |-- to -| | | |-- docxfiles -| | | |-- drama -| | | |-- dynamic -| | | |-- graphics -| | | |-- lists -| | | |-- maths -| | | |-- templates -| | | `-- wordsections -| | `-- utils -| | |-- graphics -| | |-- identity -| | |-- maths -| | `-- verbatim -| |-- epub -| |-- fo -| |-- fo2 -| |-- html -| |-- latex -| |-- latex2 -| |-- nlm -| |-- odds -| |-- odds2 -| |-- oo -| |-- profiles -| | |-- bodley -| | | `-- epub -| | |-- default -| | | |-- csv -| | | |-- docbook -| | | |-- docx -| | | |-- dtd -| | | |-- epub -| | | |-- fo -| | | |-- html -| | | |-- latex -| | | |-- lite -| | | |-- oddhtml -| | | |-- oo -| | | |-- p4 -| | | `-- relaxng -| | |-- enrich -| | | |-- docx -| | | |-- fo -| | | |-- html -| | | `-- latex -| | |-- iso -| | | |-- docx -| | | | `-- model -| | | |-- epub -| | | |-- fo -| | | |-- html -| | | |-- latex -| | | |-- schema -| | | `-- tbx -| | |-- ota -| | | |-- epub -| | | `-- html -| | |-- oucs -| | | |-- docx -| | | |-- epub -| | | `-- p4 -| | |-- oucscourses -| | | `-- docx -| | |-- podcasts -| | | |-- docx -| | | `-- epub -| | `-- tei -| | `-- epub -| |-- slides -| |-- slides2 -| |-- tite -| |-- tools2 -| |-- xhtml -| `-- xhtml2 -`-- xquery - - - - - - - - -Some other (mostly superceded) documents on the topic - - - TEI ED W9 -Points of Style For Drafts of TEI Guidelines -2 Mar 1990 -in Waterloo Script format - - - -Notes on House Style -TEI ED W11 -14 Sep 1992 -in Waterloo script -formatted text - - - - TEI ED W55 -Form for Draft Chapters of the TEI Guidelines -5 june 1996 -in TEI P2 format -in HTML format -in ODD format - - - TEI ED W57 -Procedures for Correcting Errors in the TEI Guidelines -July 23, 1994 -in TEI P2 format -in HTML format - - - - - - - diff --git a/TCW/tcw22.html b/TCW/tcw22.html deleted file mode 100644 index d050aa5..0000000 --- a/TCW/tcw22.html +++ /dev/null @@ -1,494 +0,0 @@ - - - - - - Building a TEI Release - Martin Holmes - James Cummings - Lou Burnard - Sebastian Rahtz - David Sewell - Kevin Hawkins - Hugh Cayless - Peter Stadler - Elli Mylonas - Elisa Beshero-Bondar - Raffaele Viglianti - Jessica H. Lu - - - TEI Technical Council - 2018 - - - This document was originally a section of tcw20.xml, but has now been spun off into its - own document. - - - - Per Nick Cole, since $PATH is not set up on server, need to specify - current directory in path to some executables. - Adding a step to update the version of p5subset.xml which is in the Stylesheets repo, - prior to doing any of the release steps. - Additional changes based on February 2020 release to make links visible, clarify release steps, confirm primacy of Paderborn Jenkins server. - Update all references, and add links, to Jenkins servers. Revise instructions regarding release version numbers. - Update all references about ssh to the tei server to the new HumaNum server consistently. Correct small grammatical errors. - Add updates and clarifications learned from last release. - Add information about setting JAVA_HOME for updating the Debian packages - Be explicit about contacting Jenkins maintainers ahead of time - Recommendations for issue handling that facilitate preparing the Release Notes. - Beginning edits arising out of the experiences - releasing 3.0.0. More to come. - Fixed error in git command as just reported on - tei-council - Edits for new release process. - Updates for new Jenkins server subdomains. - Update for use of ant build process for oxygen-tei rather - than the old .sh file. - More updates to account for the shift from SF SVN to - GitHub. - Updates to account for the shift from SF SVN to - GitHub. - Updates arising out of release process for 2.8.0. - Added link to http://wiki.tei-c.org/index.php/IRC - Updates to take account of oxygen-tei's move from Google - Code to GitHub, along with a couple of other tweaks. - Updates for changes in procedure ahead of the 2.6.0 - release. - Updates following move of some code from SourceForge to - GitHub, and automation of the P5 version number in output. - Updates following Primrose Path release - experience. - Newsfeed blog is no longer in SourceForge. - A few changes based on messages to tei-council on - 2012-06-19 and 2012-06-20. - Improvements suggested by various Council members based on - experiences with version 2.1.0. - Explained version numbers and added reminder about - including readme file in announcement. - Document forked from tcw20.xml. - - - - - - This document aims to provide a set of detailed instructions enabling a "release - technician" (the Council member tasked with implementing a new release of the TEI) to - prepare for and manage the release process. It assumes that the new packages will be taken - from one of the Jenkins servers rather than being built locally by the release technician. - This is easier and more reliable, because we ensure that the Jenkins servers are regularly - updated and are correctly configured to build the TEI products. - - - Packages on GitHub - The TEI maintains a number of distinct repositories on GitHub under the - TEIC organization. The main repository for developing the P5 Guidelines - and associated schemas is TEIC/TEI, and the TEI Stylesheets, the code for - the Roma web application, and the source code for the Oxygen TEI plugin can be found in - TEIC/Stylesheets, - TEIC/Roma, and - TEIC/oxygen-tei respectively. - The rest of this section describes how to make a new release for the main - P5 package, but similar procedures apply to the others. The instructions - assume you are working on a Linux or MacOSX system with a command line, and know (more or - less) how to do basic command-line operations such as running scripts and logging into a - server with ssh. - - - - What you will need before you start - - - An account on GitHub, and committer privileges over the TEI repository. If you have - ever pushed a change to the TEI repository, you should have all the - required permissions. - Shell access on the TEI SourceForge project. Contact one of the admins to have this - turned on. Normal committers don't have shell access. - The release manager will need SSH login access to the tei account on the tei-c.org - server. This involves two steps: - Generate an SSH key pair (if you don't have one already). If this is new to you, - look at https://en.wikipedia.org/wiki/Ssh-keygen. - - Send the public key to the Council Chair, who will forward it on to the system - administrator. - Make sure you get this set up well in advance of the release day, and make sure - you can ssh tei@cchum-kvm-dockerteic.in2p3.fr successfully. (Note: if you are a member - of the Infrastructure Group, you will already have your own login to the server, but you - should test it.) - - Some familiarity with the three TEI Jenkins Continuous Integration Servers. - - https://jenkins.tei-c.org - https://jenkins2.tei-c.org - https://jenkins3.tei-c.org - - Take a little time to watch them work, and see how a push to the GitHub - repository causes them to start building TEI packages. There are three specific build - jobs associated with P5, and they run in a fixed sequence. Currently, as of February 2020, - the actual build for the release will rely on the first Jenkins server, often referred to as - the "Paderborn Jenkins" (maintained by Peter Stadler in Paderborn, Germany). - Access to the TEI Council Slack - which will be the communication channel during the release process. - Several hours of time. You won't be busy all the time, but the process from - beginning to end takes several hours, especially if something goes a bit wrong and you - have to retrace your steps. It's best to start first thing in the morning, and prepare - to be busy all day. - - - A copy of the public key that will enable you to sync the release zip with - SourceForge. - log in to the tei server at ssh tei@cchum-kvm-dockerteic.in2p3.fr (this requires that you've completed - the other public key step above). (Note that if you are a member of the Infrastructure Group - with your own login, log in as yourself, but sudo su tei before running any scripts.) - cat ~/.ssh/id_rsa.pub and copy the contents to the clipboard. - paste the result into a text editor and remove any linebreaks added by the - terminal. - copy-paste the result into https://sourceforge.net/auth/shell_services - What this does is to enable you (when logged in as tei to tei-c.org) to connect - to SourceForge (as your SF user) to upload the release files. - - Test it by trying to log into SourceForge via ssh from the tei-c.org server: - ssh sfuser,tei@frs.sourceforge.net where "sfuser" is your SourceForge - user name. You should not see a prompt for a password (because of the ssh keys you have - set up). Instead, you should immediately see Welcome! This is a restricted Shell - Account. You can only copy files to/from here. If you see this, then everything is - set up correctly. - - - - - - Issue Handling Recommendations - - Assign tickets to release milestone - Use ticket reference in any commits addressing or fixing the issue - At least for the final commit addressing the issue try to prepare the commit message so it can be used for Release Notes - Label the issue as Release Note (green label) if it’s important to include the note about it in Release Notes - - - - - - Step-by-step instructions - - - 1-2 weeks before release: - - Get p5subset.xml from a fresh build of the P5 dev branch (preferably on Jenkins, at a URL such as - https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5subset.xml) and - update the version of p5subset.xml in the Stylesheets/source directory in the Stylesheets dev branch. - Inform the Jenkins maintainers (who may not be on the Council listserv), and the - TEI sysadmin, of the pending release date, so that they can be available or on-call. - Ask one of the Jenkins maintainers (Peter Stadler, Martin Holmes, and Raffaele Viglianti) - to run a link check on the Guidelines and fix broken links in the dev branch. - Ask for the TEI-C GPG key passphrase. You'll need it for signing the Debian packages. - (The GPG private key itself is hosted on the server at the default location.) - - Communicate with the TEI Council chair to make sure that the P5/ReleaseNotes/readme-X.X.X.xml - is compiled Normally, this will be created by the TEI Council chair at the - point when the repository moved from its "alpha" stage to "beta", following these steps: - Confirm the version number for the new release in consultation with Council. TEI - version numbers are based on the Unicode Consortium system (http://www.unicode.org/versions/) but with the first digit for major - changes, the second for schema-changing revisions, and the third for - non-schema-changing revisions. When the first or second digit is incremented, the - following digit or digits is set to zero. During initial development, the version - number is followed by "alpha"; during the pre-release checking stage, it's followed - by "beta"; and when the release takes place, "beta" is removed and the version - number has only digits and periods. - Create the new file by cloning a previous one. - Consult the git log log to check for all the significant changes since the last - release. You can do this by opening a terminal in the root of a working copy of the - TEI repository and running: - git log --after=2015-08-01 where the date is that of the previous - release. - Add the new file into the repository with git - add. - - - At least one week before releasing, we enter a review period, during which the only - changes made to the code to be released should be to fix errors, rather than to add new - features. Release branches for the TEI and Stylesheets repos will be created by the release technician, to which ONLY - release-blocking bug fixes and corrections to typographical errors will be pushed. The - release technician should announce a temporary hold on pushes to the dev branches on the - Council list, then create the branches and push it to GitHub using the following commands, once in the - TEI repo and once in the Stylesheets repo: - git checkout dev (make sure you start from the dev branch) or if you have the dev branch - checked out, git status in order to make sure that you have the current version and no uncommitted changes. - git checkout -b release-X.X.X - git push -u origin release-X.X.X - Immediately after the release branches have been pushed, - the release technician should inform the Council - list and ask the maintainers of the TEI Jenkins - systems to add a build of the release branch so that commits - pushed there are properly tested, and advise them of the - release schedule. Remember that the maintainers (currently - Martin Holmes, Peter Stadler, and Raffaele Viglianti) may not be on the Council - list. Verify with the maintainers that all Jenkins servers are functioning properly. - Pushes to the release branch should be merged back into dev regularly: - git checkout dev - git merge release-X.X.X - - - - On release day: - The instructions below for Git commands are assumed to be run in the release-X.X.X - branches unless otherwise specified. If you did not create the release branch, you can - set up a copy of it using the following commands: - git pull origin (to make sure your copy knows about the release branch) - git checkout --track origin/release-X.X.X - - Check the release notes for typos or other glaring errors, one last time. - Edit the P5/VERSION file to the correct number This file - consists only of the bare version number, followed by "alpha" or "beta": - 2.8.2beta For the release process, you need to remove the letters from - the end, leaving a pure version number: - 2.8.2 This changes the release from beta (or possibly alpha) to the - actual release version number. - - - Get p5subset.xml from a fresh build of the P5 release branch (preferably on Jenkins, at a URL such as - https://jenkins.tei-c.org/job/TEIP5-release-X.X.X/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5subset.xml) and - update the version of p5subset.xml in the Stylesheets/source directory in the Stylesheets release-X.X.X branch. - Announce a freeze on pushes to the release branch on the - TEI Technical Council mailing list - Merge the release branch into released. - git checkout released - git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X - Repeat the steps above for the Stylesheets (have a stylesheets expert on hand - when releasing Stylesheets to help debug problems): - - Edit the Stylesheets/VERSION number to the correct release number (usually just - remove the 'a'). - Run make log to generate the changelog. Then commit the changes. - Merge the release branch into released - git checkout released - git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X - - - - Push your changes for both P5 and the Stylesheets to the git - repository, git push origin released and watch Jenkins build P5 for you. - This should be the final push for this version, and it will trigger the Jenkins servers - to rebuild the TEI packages. As a reminder, you can find the Jenkins servers here: - - https://jenkins.tei-c.org - https://jenkins2.tei-c.org - https://jenkins3.tei-c.org - - And now you wait while the Jenkins servers build the packages, keeping in mind that - subsequent steps will require the build packages from the Paderborn Jenkins server - (as of February 2020). This can take a couple of hours, so be patient. - - Note: The P5 and Stylesheets builds have reciprocal dependencies, - so the first build of either the Stylesheets or the Guidelines may fail just because - there isn't yet a current build of the other for it to use. This isn't a cause for - panic, but it may mean that (e.g.) the Stylesheets build needs to run twice. In particular, - the Stylesheets build may fail after the TEI release is complete, so it is better to wait - until the TEI release is complete before doing the Stylesheets release. (Council is considering - changing how the dependency is managed). - Ensure all changes have been committed, built, and successfully - passed tests on the continuous integration server When all builds have - completed on all Jenkins servers, click on the job number of the last build for each of the - three TEI jobs to make sure that it was triggered by the commit that you made in the - previous step (you should see your own commit message on the build page). Make sure that - all builds were successful (they should have green balls next to them). In the case of red balls, - indicating a failed build, seek support via the TEI Council Slack. - - Log into TEI server and run the tei-install.sh script: - Log into the TEI server via ssh tei@cchum-kvm-dockerteic.in2p3.fr. - Note that if you are a member of the Infrastructure Group - with your own login, log in as yourself, but sudo su tei before running any commands. - Then fetch the current version of the install script by issuing - curl https://raw.githubusercontent.com/TEIC/TEI/dev/P5/Utilities/tei-install.sh -o ~/tei-install.sh. - (If you'll need to tweak that script later during the install process please make - sure to feed the changes back to the original script in the TEI repo.) - Do the following three steps: - Install on tei-c.org: ./tei-install.sh --package=TEIP5 --version=X.X.X - --sfuser=username --install and then go test the version this puts in - the Vault. - If that looks good and everyone agrees then: ./tei-install.sh - --package=TEIP5 --version=X.X.X --sfuser=username --makecurrent and - then test that it appears on website correctly. - If the website looks right then: ./tei-install.sh --package=TEIP5 - --version=X.X.X --sfuser=username --upload and then move on to the next - step. - - In each of these steps, replace the Xs with your release version. Supply your - SourceForge user name, and type your SourceForge password when prompted. By default, the - script will pull the release package from the first Jenkins server, but you can supply - the URL of the other server if necessary with the --Jenkins parameter, e.g. - --Jenkins=http://jenkins2.tei-c.org/. Make sure the script completes successfully each time - changing the final parameter from --install, to --makecurrent, and then --upload. - - Repeat the steps above for the Stylesheets, remembering that the version number is the Stylesheets version, which will be different from - the Guidelines version: - ./tei-install.sh --package=Stylesheets - --version=X.X.X --sfuser=username --install - ./tei-install.sh --package=Stylesheets - --version=X.X.X --sfuser=username --makecurrent - ./tei-install.sh --package=Stylesheets - --version=X.X.X --sfuser=username --upload - - - - Check the TEI website and all downloadable files are displaying the - correct version Everything should now be done, so go to the newly - released version on the TEI site and browse the Guidelines. Check that your - version number is displayed in the footer of the page, and check that at least one - change made since the last release is being reflected online. - - Update Roma, - Romabeta, and OxGarage - Change to the directory ~/repos/infrastructure/humanum and issue the script - docker-update.sh for every service, i.e. - - # ./docker-update.sh roma - # ./docker-update.sh romabeta - # ./docker-update.sh oxgarage - - NB: Every invocation might take some time but each should succesfully finish with the notification - "Creating $CONTAINER$ ... done" - - - - Make your release the default downloadable version from - Sourceforge Go to the SourceForge site (https://sourceforge.net/projects/tei/files/TEI-P5-all/), - log in, and click the information button on your new release. Make it the default download for all - operating systems. Now make sure that the main Download button links to your package. - - - Update tags on GitHub Every time a new release is made, a - "tag" is created consisting of a pointer to the state of the P5 tree at release time. - You can do this from the command line on your own computer. Before moving forward, be - sure to do a git pull and update your released branch. Then, still in the released - branch, do: - git tag -a P5_Release_X.X.X -m "Release X.X.X of the TEI Guidelines." - where X.X.X is your new release. Then - git push origin P5_Release_X.X.X - - - Make a Release on GitHub Go to the TEI Tags page at https://github.com/TEIC/TEI/tags on GitHub. You should - see the tag you just pushed there. Click on it and then click on "Edit Release". Add a link to the release notes README, which should be at - https://www.tei-c.org/release/doc/tei-p5-doc/readme-X.X.X.html, into the text box. Add a copy of the zipped - release by downloading it from https://jenkins.tei-c.org/job/TEIP5/lastSuccessfulBuild/artifact/P5/ and then uploading it to the release page. - - Close/Add GitHub Milestones Go to the Milestones page of both the - Stylesheets and the - Guidelines repo. Add new Milestones by - incrementing the minor version number part and move all open issues from the current Milestone to the new one. - (If Council already decided on the next release date (unlikely) you can add the date to the new Milestone. Otherwise leave empty.) - Finally, close the current Milestone. - - Update the Debian Package repository with the new release - The TEI Debian packages are regularily created during each Jenkins build. - For each release you need to update the TEI Debian repository at - http://packages.tei-c.org/deb/ - which can be done by simply running ant on the TEI server within the - /data/debian-packages directory. - (This directory is cloned from https://github.com/TEIC/TEI-apt-repo) - Since the repository index needs to be signed, you'll need the passphrase for the GPG key. - Make sure you've received it in advance! - Once the process has finished and the repo is updated, the page at http://packages.tei-c.org/deb/ - should reflect the changes immediately. If not, try to restart the NGINX Docker container that serves this directory - with docker restart debian-packages. - - - - Update the list of previous releases of P5, which is found at https://tei-c.org/guidelines/p5/#section-2. - If you have editing privileges on the TEI WordPress on tei-c.org, add the new release to the top of the release table. If not, ask one of the - other Council members who does (currently Martina Scholger and Hugh Cayless) to make the change. - - Update the oXygen-ready distribution of TEI. This involves - building the new package of oxygen-tei, and then updating the distribution file on the - TEI server so that the oXygen software knows about the new release. You may request to - hand this off to one of the maintainers (currently Syd Bauman, James Cummings, or Martin - Holmes) to do this for you if you're not familiar with the project. - Check that you have ant (at least version 1.8) installed on your machine. - - - Check that the latest versions of the TEI Stylesheets and TEI P5 packages are - available for download from the TEI server, since the oxygen-tei - update/upload script retrieves them from there. - - Check out or update a local copy of the source code from https://github.com/TEIC/oxygen-tei to your local system. - - cd into the oxygen-tei folder (it should contain folders called "frameworks" and - "jenkins"). - - Run the ant build process with the "release" parameter: - ant release This builds the plugin using the latest stable - versions of P5 and the Stylesheets, then offers to upload the result to the TEI's - SourceForge repo to become a release of the TEI-maintained version of the plugin. - This also creates an updated updateSite.oxygen file, by retrieving the latest - updateSite.oxygen file from the tei-c.org site, and asks the user to provide the new - version number before creating a new version of updateSite.oxygen. - - Go to the GitHub repo and create a new release, using the Draft new release - button. Copy the previous release info (tag, title and text), and tweak the versions as appropriate. The tag should be vx.x.x, the title will be - Release x.x.x, and the text Release number X of the oXygen TEI plugin, based on TEI P5 x.x.x and Stylesheets x.x.x. - - Attach the zip file you just created in the build process, which will be named - something like oxygen-tei-x.x.x-x.x.x.zip, with the numbers from - the current TEI and Stylesheets releases. - - Once the tag/release has been published, run ant uploadOxygenUpdateFile - to push the updateSite.oxygen file up to the TEI server. - - - - Inform the TEI Technical Council Chair so they can announce the - release Once you are sure that everything is working correctly, inform the - Council Chair. They will announce the release to the TEI-L mailing list, including the - text of P5/ReleaseNotes/readme-X.X.X.xml in plain text form (which can be generated - using the "readme" profile for teitotxt), and place an announcement on the Text Encoding - Initiative Newsfeed blog in the category of 'News'. - Lift the freeze on committing changes to the repository - Write to the TEI Council list and let them know that they can once again start - committing changes to the repository. - - Increment the build number for the next release cycle - Recalling how release preparation requires confirmation of version number, - use your best judgment to determine the version number for the next release (in consultation with Council, - if possible). TEI version numbers are based on the Unicode Consortium system (http://www.unicode.org/versions/) but with the first - digit for major changes, the second for schema-changing revisions, and the third for - non-schema-changing revisions. When the first or second digit is incremented, the - following digit or digits is set to zero. - - - - After the release process has been completed, the release number for both P5 and the - Stylesheets needs to be updated. On the dev branch, edit the P5/VERSION file and the Stylesheets/VERSION - file to the correct numbers. These files contain nothing except the bare version number. - It should be incremented appropriately, and "a" added to the end of it, so if for example - the release was number 2.8.0, you would change the number in the file to: - 2.9.0a signifying that the versions built subsequent to the release - are now in the alpha stage. - - - - - - - - - - - diff --git a/TCW/tcw24.html b/TCW/tcw24.html deleted file mode 100644 index 3a4e29b..0000000 --- a/TCW/tcw24.html +++ /dev/null @@ -1,349 +0,0 @@ - - - - - - Style Guide for Editing the TEI Guidelines - TEI Technical Council - - - TEI Technical Council - 2018 - - - The first draft of this document was created by moving the "House Style: preferred - orthography" and "House Style: notes on usage" sections from TCW20, "How to Edit the TEI - Guidelines" to their own document, TCW24, which will serve as a full style guide for the - Guidelines. - - - - Added section on modal verbs - Added egXML guidance - Link to BCP 14 - Fixed ptrs - "TEI header" is preferred - Explained -ize vs. -ise. Also a markup fix. - desc's for attributes should also be verbal phrases - Added note about desc elements containing verbal - phrases; some light copyediting - Adding prose about use of first-person/"we" and - second-person/"you" in the Guidelines. - started first draft: moving sections from TCW20, "How to - Edit the TEI Guidelines" to their own document. Re-ordered some sections, proofread, added - some examples, and added discussion of hyphenation. - - - - - This document aims to capture decisions about House Style for writing and editing the TEI - Guidelines, in order to maintain consistency throughout the Guidelines. - - Tone and voice - The Guidelines are a reference manual, not a tutorial. You should not talk down to the - reader, but assume they have a reasonably well-informed knowledge of the subjects under - discussion. Make copious use of cross references, rather than repetition. - Bear in mind however that your reader may not have English as their first language. Avoid - needlessly complex sentences and unnecessarily obscure terminology. - Choose clarity and concision over adherence to any particular voice. However, you should - be careful in your use of the first person, avoiding the implication that a community of - scholars, or the whole TEI community, takes a certain view. The use of "we" is appropriate - in passages of formal textual exposition, where "we" refers to both the reader and the - authorial voice. For instance: "Each chapter of the Guidelines presents a group of related - elements, and also defines a corresponding set of declarations, which we call a - module." - Avoid the use of a first-person authorial voice that does not include the reader as part - of "we." For instance: "We do not describe them in detail here," which refers to a - particular editorial decision made by the authors of the Guidelines. In this case, "They - are not described in detail here" is preferred. - As a test, ask yourself whether the material being asserted, typically a technical term - or usage, is something the reader is expected to internalize and use themselves - thereafter. If so, use "we." If not, it is more appropriate to use the passive voice. - In general, avoid imperative constructions ("you should..."). However, key words like - "should", "must", "must not", "recommended", etc. should be used in accordance with - BCP 14. - - - - General notes on usage - This is a list of notes on usage preferences and conventions, which we expect to expand - over time. - - Gender-neutral pronouns - We prefer the usage "they", "their" etc. where the third person singular is - required, but gender is unspecified. For instance: "The encoder may follow their own - preference here." This is less ungainly than "his/her" etc. - Technical terms - Make sure that technical terms are glossed on their first appearance. For instance, - XML-related terminology should be introduced in the chapter on XML. If you want to - provide other references, do so as footnotes, using the note element. - References - Provide bibliographic citations for any other standards (etc) referenced, following - the existing style. Do not introduce bibliographic citations simply in order to - demonstrate your learning. - Descriptions in specifications - The description of an element, attribute, model class, or attribute class contained in - desc should always be a verbal phrase beginning with a present-tense verb - ("contains a ...", "groups together ...", etc.) - Internal references - Language like "the preceding" and "the following" should not be used to refer to specific figures, tables, and examples. Instead, be sure there is an xml:id on the object in question and link to it with ref. - - - - Naming conventions - TEI naming conventions have evolved over time, but remain fairly consistent. - - generic identifiers - Element and attribute identifiers should be a single natural language word in - lowercase if possible. For instance: bibl. If more than one word is conjoined - to form a name, then the first letter of the second and any subsequent word should be - uppercased. For instance: biblStruct. Hyphens, underscores, dots etc are not - used within element or attribute names. - class names - Class names are made up three parts: a name, constructed like an element name, with - a prefix and optionally a suffix. The prefix is one of model. or - att. and indicates whether this is a model or an attribute class. The - suffix, if present, is used to indicate subclassing. For example - att.linking.foo is the foo subclass of the attribute - class att.linking - xml:id values - The conventions for these vary somewhat. Most of the older chapters of the - guidelines have consistently constructed identifiers, derived from the individual - section headings. Identifiers must be provided for:- - every div, whether or not it is explicitly linked to elsewhere - every bibliographic reference in the BIB.xml file - - - - - Capitalization of headings - Use title case as defined in the Chicago Manual of Style for - all headings (i.e. all text in head elements that occur as children of div - elements). - - - - - Preferred orthography - The goal of these rules is to avoid inconsistency, and also (wherever possible) to avoid - producing text which is markedly either British or American English. For example, use the - "-ize" suffix instead of "-ise" for words that are a Latinized version of a Greek suffix because - while both spellings are given in the Oxford English Dictionary, only the "-ize" form is used - in American English. The following table - lists the preferred word-spacing and hyphenation for a number of frequently-used terms: - - Word or Term - Authority/explanation - - - code point (n.); code-point (adj.) - UCG [discussed on TEI Council list] - - - cross-reference - MW, OED - - - data set - OED - - - datatype - [OED, ORDS have 'data type', but Guidelines consistently use single word dozens - of places] - - - email (not *e-mail) - commoner usage; consistency with JTEI; name of TEI element; bug #664 - - - end-tag - ORDS - - - GitHub - - - - TEI header; the <teiHeader> - [discussed on TEI Council list in January/February 2013] - - - high-level (adj.) - MW, OED - - - line break - - - - lowercase/uppercase - MW, ORDS - - - proofread - MW, OED - - - SourceForge - - - - start-tag - ORDS - - - stylesheet - ORDS - - - typeface - MW - - - the Web - ORDS - - - web page - ORDS - - - web site - ORDS, OED - - - well-formed (even in a predicate usage: "the XML is well-formed") - W3CXML - - - whitespace - ORDS - - - - The abbreviations above refer to the following list of authorities, which may also be - consulted for other vexed issues: - CMS - Chicago Manual of Style, 15th ed. - MW - Merriam-Webster's Collegiate Dictionary, 11th ed. - OED - Oxford English Dictionary, 2d ed. online () - ODE - Oxford Dictionary of English (aka NODE), 2d ed. - ORDS - O'Reilly Default Stylesheet, - UCG - Unicode Consortium Glossary, - W3CXML - W3C XML Recommendation, - - - - - Punctuation - - Em dashes - Only em dashes should be used parenthetically (do not use en dashes or hyphens for - this purpose). There should be no spaces around them when they are used in this way. The - only exception to the above (currently) is where we refer to the titles of ISO - documents, where we must follow the ISO practice of using spaces. - En dashes - En dashes should be used for numerical ranges such as dates, page-ranges, etc. En - dashes should not have spaces around them. - - - - Conventions in egXML - - Elided elements - Very often, examples will omit markup, even markup that would ordinarily be necessary - for the example to be valid. Such elisions should be marked with an ellipsis inside a - comment, usually on its own line, thus: - <!-- ... -->. - Elided text - Similarly, examples often omit text that doesn't serve the purpose of the example. - Such text is to be marked with an ellipsis in square brackets, thus: [...]. - - - - - The use of modal verbs - In general the TEI guidelines try to be careful when using modal verbs and phrases such as 'must', 'must not, - 'should', 'should not' and 'may'. In terms of the meanings, these generally follow https://tools.ietf.org/html/bcp14 in the different meanings of these words. - In particular: - - MUST - This word, or the terms "REQUIRED" or "SHALL", mean that this is an absolute requirement of the TEI Guidelines - for production of a TEI conformant file. - MUST NOT - This phrase, or the phrase "SHALL NOT", mean that this is an absolute prohibition of the - TEI Guidelines for production of a TEI conformant file. - SHOULD - This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in - particular circumstances to ignore a particular recommendation, but the full implications - must be understood and carefully weighed before choosing a different course. - SHOULD NOT - This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in - particular circumstances when the particular behavior is acceptable or even useful, but the full implications - should be understood and the case carefully weighed before implementing any behavior so described. - MAY - This word, or the adjective "OPTIONAL", mean that a recommendation is truly optional. One user may - choose to follow the recommendation because a particular project requires it or feels that - it enhances their work while another project may choose to not follow this recommendation. - - Periodic reviews of new prose must be carried out by the TEI Technical Council to ensure the use of modal verbs and phrases is clear. - - - - - - Some other (mostly superseded) documents on the topic of style - - - TEI ED W9 - Points of Style For Drafts of TEI Guidelines, - 2 Mar 1990 - (in Waterloo Script format) - - - - TEI ED W11 - Notes on House Style, - 14 Sep 1992 - (in Waterloo script, - formatted text) - - - - TEI ED W55 - Form for Draft Chapters of the TEI Guidelines, - 5 june 1996 - (in TEI P2 format, - in HTML format, - in ODD format) - - - TEI ED W57 - Procedures for Correcting Errors in the TEI Guidelines, - July 23, 1994 - (in TEI P2 format, - in HTML format) - - - - - - - - diff --git a/TCW/tcw27.html b/TCW/tcw27.html deleted file mode 100644 index b708aa9..0000000 --- a/TCW/tcw27.html +++ /dev/null @@ -1,87 +0,0 @@ - - - - - - Procedure for handling practices that are no longer recommended or - deprecated - Kevin Hawkins - - - - 2013-05-16 - - - - freely available - - - Manually reformatted from http://wiki.tei-c.org/index.php/Practices_no_longer_recommended_or_now_deprecated - - - - Removed step about creating Schematron warning: Syd says they're generated automatically based on presence of @validUntil. - Added standard wording for Schematron warnings and instruction to notify TEI-L of planned deprecations - Copyediting - Added more missing markup from wiki - Added link to tcw09 (Birnbaum doctrine) - - - - - - At its April 2013 face-to-face meeting in Providence, the Technical Council agreed to - the following policy for handling practices that are "no longer recommended" or - "deprecated". - - - No longer recommended - - While the TEI Guidelines often offer more than one way of encoding a particular - phenomenon, in this case the Council agrees to identify a preferred method without - making any definite plans to remove the non-preferred way from the Guidelines. In - this case: - - The remarks element is used in the spec to indicate the preferred - practice. - The prose in one or more chapters is revised to indicate this preferred - practice. Examples showing the non-preferred practice are maintained but - preferably only in the section of the Guidelines where that element or - attribute is discussed, not in passing elsewhere. - - - - - Deprecated - - Following the Birnbaum doctrine, the Council has made the serious decision to - break backwards compatibility by changing the content model of an element or class - to remove an element or attribute, or to remove an element or attribute entirely - from the Guidelines. In this case: - - The appropriate specification is given a validUntil attribute indicating the intended date - after which the specification will be withdrawn. Specifications which can be deprecated this way are all - members of the class att.deprecated. - An announcement is sent to TEI-L that the Technical Council has decided to - depreacate elementName and will drop it as early as YYYY-MM-DD. If anyone strongly objects, - they should reply to the list so that the Council might reconsider. - Any examples of the deprecated practice are removed from the Guidelines, and - any prose recommending them is reworded as appropriate. - We will try to remember to include a mention of the deprecation in the - release notes created for the following release. - - - After the date specified in validUntil: - - The element or attribute is actually removed from the spec. - - - - - - diff --git a/TCW/tcw29.html b/TCW/tcw29.html deleted file mode 100644 index 74e6efa..0000000 --- a/TCW/tcw29.html +++ /dev/null @@ -1,162 +0,0 @@ - - - - - - The Roma install on tei-c.org - Martin Holmes - - - - 2015-12-29 - - - - freely available - - - Born-digital document - - - - - - - - During the fall of 2015, Martin Holmes and Ian Rifkin worked on deploying a new version - of Roma with a minor bugfix on tei-c.org, and formalized a previously rather ad-hoc setup - so that future bugfixes and updates might be less mysterious. This document explains how the - current setup works, and how to deploy an updated version of Roma. - - - - - Where is Roma on tei-c.org? - - Roma, a helpful but rather outdated front end which enables people to create customized - ODD files and schemas in a GUI interface, is available for public use here: - - http://www.tei-c.org/Roma/ - - If you click on "Start" to enter the process, you will see that the footer of the page shows - detailed information about the current Roma version as well as the version of P5 it is using. - - - If you have permission to log into the tei-c server, you will find it quite difficult to - locate the actual running versions of Roma; they are (for largely historical reasons) located in - - /var/www/vhosts/tei-c.org/opencms_tomcat/usr/share - - - In that directory, you will find multiple versions of the Roma codebase, in folders named for their - versions: - - - tei-roma-4.15 - tei-roma-4.18 - - - Each of these versions is working and available on a special URL based on its version number: - - - http://www.tei-c.org/Roma-4.15/ - http://www.tei-c.org/Roma-4.18/ - - - In addition, there is a symbolic link, which at the time of writing points thus: - - - tei-roma -> tei-roma-4.18 - - - This means that the current "live" version is 4.18. - - - - - How to deploy a new version - - Although Roma is not currently in active development, from time to time, bugfixes may be - made and new versions deployed. This is how to do that: - - - Fix bugs on the GitHub repository. - Check out a fresh version from the GitHub repo into a folder in the deployment location, - naming the folder based on the version number of the new version: - - /var/www/vhosts/tei-c.org/opencms_tomcat/usr/share/tei-roma-4.20 - - - Test the new version thoroughly using its version-based URL: - - http://www.tei-c.org/Roma-4.20/ - - which will be available automatically through the Apache configuration. - - When you are confident that it's working correctly, ask the server administrator - (currently Ian Rifkin) to update the symbolic link so that it becomes the current live - version. (You may be able to do this yourself.) - - - - - Configuration of Roma to run on tei-c.org - - The configuration of Roma is controlled by a number of files: - - VERSION, which contains the Roma version number. When doing a bugfix, don't forget - to update this file. - roma/config.php, which has all the URLs pointing to OxGarage and the eXist XML database - required for Roma to function, as well as some local paths. It is recommended that you copy the config.php - from the previous live version of Roma into a new deployment, and then just make a couple of required - tweaks (such as changing the release date and the version number). - roma/templates/main.tem. Due to a bug, - this file must also be updated to provide the date of the roma release, in order for the correct date - to appear in the footer of pages. - - - - - - What does Roma depend on? - - - Roma does not do a great deal of real work itself. Instead, it requires a number of resources and services - in order to work; these are apparent in the configuration file: - - - define ( 'roma_xquery_server', 'http://www.tei-c.org/Query/' ); - - - Roma uses the P5 Subset file retrieved via an XQuery call to the eXist XML - database running on tei-c.org as a source of - information on the modules, classes, elements and attributes available in the current release version - of P5. That's why the eXist XML database must be updated as part of a P5 release. - - - define ( 'roma_teiweb_server', 'http://www.tei-c.org/release/doc/tei-p5-doc/' ); - - - In other operations such as adding elements and attributes to a schema, it retrieves information - from the current live version of TEI P5 on the tei-c server. - - - define ( 'oxgarage_server', 'http://www.tei-c.org/ege-webservice'); - - - Finally, in order to transform an ODD file into a schema or into documentation, it calls on - the web service provided by OxGarage. - - In order for Roma to function correctly, all these services have to be updated to matching - versions, including (in the case of OxGarage) the latest version of the Stylesheets. - - - - - - diff --git a/TCW/tcw30.html b/TCW/tcw30.html deleted file mode 100644 index d5c11ed..0000000 --- a/TCW/tcw30.html +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - TEI Council: Workload and Guidelines for Resignation - Syd Bauman - Elisa Beshero-Bondar - Jessica Lu - - - - 2020-06-29 - - - - freely available - - - Born-digital document - - - - - - - - TEI Council: Workload and Guidelines for Resignation - - Workload - Once elected, your voluntary membership on the TEI Council is both an - opportunity and a responsibility. The TEI and its community rely upon the - Council’s consistent attention and engagement. While the Council shares and - distributes duties among its members, each individual Council member can - expect to devote, at a minimum: - Several scheduled and self-paced hours, monthly, to “orientation” - and mentorship during the first year of Council service; - 3 scheduled hours, monthly, to virtual conferencing for the - duration of your elected term; - 4+ self-paced hours, monthly, to addressing tickets and other - Council tasks (e.g. server maintenance, listserv correspondence, - special projects, etc.) after your orientation and for the duration - of your elected term; - 10 days, annually, to two face-to-face Council meetings and - associated travel (expenses reimbursed). - - - Furthermore, Councilmembers are encouraged to submit original work for peer - review and presentation at the annual TEI Conference and Members’ - meeting. - - - Resignation - Occasionally, a Council member may be unable to meet the demands of their - work on the Council. While temporary absences (due to illness, - financial or personal hardship, etc.), are certainly acceptable, Council - members should communicate their needs for accommodations. Council members - who must disengage from Council work for an extended period are asked to - vacate their elected position in a timely manner. - Resignation should be strongly considered if: - A Council member is unable to attend all-Council virtual - conferences for three consecutive months, or is unable to attend at - least half of the all-Council virtual conferences over the course of - a six-month period. - A Council member is unable to assume responsibility for any - regular Council tasks (including, but not limited to, minutes - review, ticket triage, and ticket review) for three consecutive - months. - A Council member is unable to attend both the annual face-to-face - all-Council meeting and the annual TEI Conference and Members’ - Meeting in a given year. - - - - Process - When Council members are considering resigning from their elected - position, we ask that they: - Discuss the situation with their mentor or another Council - member first - a) to discover whether accommodations other than their - departure might be made that would mutually benefit both - the member and the Council; and - b) to ensure that Council can prepare for their - absence and reassign their work. - - - Submit an official message of resignation from their elected - position via email to the Council chair. - - - A Council member’s resignation will activate a provision of the TEI-Consortium Bylaws and may initiate the process for a special election or - appointment to fill the vacated position. - - - - - - - diff --git a/TCW/testing_and_building.html b/TCW/testing_and_building.html deleted file mode 100644 index f38bcb4..0000000 --- a/TCW/testing_and_building.html +++ /dev/null @@ -1,131 +0,0 @@ - - - - - - Building and Testing the TEI Guidelines and Stylesheets - Hugh Cayless - - - TEI Technical Council - 2016 - - - Born digital document. - - - - - - - How to build and test the Guidelines and Stylesheets - Getting set up to run the various building and testing targets in the Guidelines and - Stylesheets is relatively easy in Debian-based Linuxes like Ubuntu. But it is quite tricky on - other systems, like Mac OS X or Windows. The TEI Jenkins server will run a variety of - builds when you push changes to the TEI or Stylesheets repos, but you may find you prefer - to run the tests locally, as they will likely be faster and will save you the trouble of - waiting for Jenkins to email you when it finds a problem. Moreover, if you’re doing work - in a branch, Jenkins won’t help you at all, and it can be very useful to “check your work” - as you go to avoid lots of bug-fixing when your merge back into dev. - The first step in setting up your development and testing environment is to get copies of - the TEI and Stylesheets repositories. These can be obtained from and respectively. All of the following - instructions assume you are at least somewhat comfortable working in a command line - environment. If you aren’t, this would be a good time to learn. A rather Mac-biased - tutorial may be found at “Learn Enough Command Line to Be Dangerous”, while Windows 10 users may learn how - to install a Bash shell and the basics of using it at “How to Install and Use the Linux Bash Shell on Windows 10”. Once you’re in a - terminal window, you can clone the TEI repos thus: - git clone git@github.com:TEIC/TEI.git and - git clone git@github.com:TEIC/Stylesheets.git - - It’s probably a good idea to keep these side-by-side. I put mine in a directory called: - /Users/hcayless/Development/TEIC. As you will see, it’s a good idea to do - this somewhere under the Users directory, whether you’re on Mac or Windows. If you’re - running Ubuntu or some other Linux, you can put them where you like. Let’s assume you’ve - got working copies of the TEI and Stylesheets repos, and that you’ve made some changes - you’d like to test before you push them back up to GitHub and make them available to - everyone. The TEI has set up a pre-built test environment in Docker that you can use. - First, you should get Docker Community Edition (CE). On a Mac, go to , on Windows, , and on Linux, choose your specific platform here: . Follow Docker’s “Get Started” instructions for your installation to configure Docker and include the TEI repositories in your Docker container. Once you have Docker - installed and set up, you can run docker pull teic/teidev-docker - to grab a copy of the pre-built image. - Now you’re ready to run your test environment. You’ll need a couple of pieces of - information for Docker: the location of your repositories and your timezone. You can look up your timezone at Wikipedia. - You need it because the default timezone of the container is UTC, which will lead to - strange warnings when you run the builds unless you actually happen to be in sync with - UTC, because the local time of your computer will differ from that set in the container. - The directory containing your repositories will be mapped to a directory in the container - (which is why it’s easier to put them side-by-side). You’ll run the test container with a - command like: - docker run --name tei -v /Users/hcayless/Development/TEIC:/tei -it -e TZ=America/New_York - teic/teidev-docker - which will put you in a Bash shell inside the container (named 'tei'), at the root directory. - The directory on your local file system where you cloned the TEI and - Stylesheets repos is mapped to /tei in the container (that’s the part after - -v above). If you then do cd tei and then ls, you - should see the repos you cloned above. There’s one more piece of work to be done, and - that’s to tell the Guidelines build process where it can find your copy of the - Stylesheets. You do that by adding a local.mk file in TEI/P5. - So, (from /tei) do cd TEI/P5 and then - echo "XSL=/tei/Stylesheets" > local.mk. Now - you can build things! And, what’s more, you can work on the Guidelines and Stylesheets in - your regular environment, and test them in Docker. The Docker command above will create a - container named “tei”, which you can return to later. Because it runs a Bash terminal, you - can exit it by typing exit at the command prompt, and that will stop the - container. You can restart it with a command like docker start -ai tei, which - will start the container and attach your terminal to it, with whatever state it was in - when you left it. You may want to alias a simple command like teidocker to - docker start -ai tei. - - To build the HTML version of the Guidelines, for example, you can run (in - /tei/TEI/P5) make html-web, and after the process finishes, - you’ll have a directory called “Guidelines-web” in your P5 directory. Outside your Docker - shell, you can browse to this folder, find the index.html file, and open it in a browser. - “Make” is a program typically used for compiling programs, but it’s also very useful as a - kind of generic batch scripting tool, which is how it’s being used here. In the - Guidelines, you’ll typically want to run Make inside the P5/ directory and in - the Stylesheets, you’ll want to run it at the top of the repo (in - Stylesheets/. You can also run Make in any directory that contains a - Makefile. Note that the targets may vary. Running make inside - Stylesheets/Test is pretty much the same as running make test - one level up. You can also run individual test targets if there’s a particular set - of tests you want to troubleshoot (e.g. make test-oddity in - Stylesheets/Test to test ODD-conversion methods). The targets are all defined - in the Makefiles. - The Using the TEI GitHub - Repository document has more detail on all the processes you can run, and very - meager information on how to get set up to run them—but you just bypassed all that. - Besides the make targets listed there, both the TEI and Stylesheets repos - have make test targets which get run by Jenkins when you push to GitHub. - These are both good ways to check your code before pushing. Make does lots of things when - you run any of these targets, but all of them should finish with a “BUILD SUCCESSFUL” - message. If there’s a problem, you’ll get a failure message, hopefully with some - indication of what went wrong. If you’ve run a build target, you probably want to run a - make clean before doing it again to make sure files that were generated - during the last run don’t interfere with your next build (Make tries not to repeat itself, - so if it finds existing build artifacts, it won’t rebuild them). Targets can be put - together, so you can do make clean test, and it will clean things up before - running the test target. - When you run the tests and other build targets, you’ll see masses of text written out, - most of which can be ignored. If one of the processes errors out, Make should stop - running, so the last thing in your terminal should tell you what happened. This may not be - a very useful message, so you might need to isolate the command that Make ran and run it - yourself to see the error messages. In the Stylesheets, errors are often in the form of - differences between the expected output of certain tests and the actual output. Test - failures here aren’t necessarily errors—if you changed something to do with ODD - compilation or schema generation, your new output might be correct but different from the - old. When this happens, you can copy the new output from the Test/ directory - into Test/expected-results. You’ll want to be a bit careful that your new - output is actually correct, of course, because now the test will pass even if it’s not - really working, because all it’s checking is whether the test output is the same as what - it expects. - Good luck and happy testing! - - - - - diff --git a/index.html b/index.html index 1e58d7c..9e9c935 100644 --- a/index.html +++ b/index.html @@ -2,11 +2,9 @@

TEIC GitHub IO Repository

-

These are just temporary development pages and should not be linked to.

+

These are typically development resources. Please user resources please go to https://tei-c.org/.