Style Guide for Editing the TEI Guidelines 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 (http://dictionary.oed.com/)
ODE
Oxford Dictionary of English (aka NODE), 2d ed.
ORDS
O'Reilly Default Stylesheet, http://www.oreilly.com/oreilly/author/stylesheet.html
UCG
Unicode Consortium Glossary, http://unicode.org/glossary/
W3CXML
W3C XML Recommendation, http://www.w3.org/TR/xml/
 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)