Style Guide for Editing the TEI Guidelines
- Tone and voice
- General notes on usage
- Naming conventions
- Capitalization of headings
- Preferred orthography
- Conventions in egXML
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.
- 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.)
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).
|Word or Term||Authority/explanation|
|code point (n.); code-point (adj.)||UCG [discussed on TEI Council list]|
|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|
|TEI header; the <teiHeader>||[discussed on TEI Council list in January/February 2013]|
|high-level (adj.)||MW, OED|
|web site||ORDS, OED|
|well-formed (even in a predicate usage: "the XML is well-formed")||W3CXML|
- Chicago Manual of Style, 15th ed.
- Merriam-Webster's Collegiate Dictionary, 11th ed.
- Oxford English Dictionary, 2d ed. online ( http://dictionary.oed.com/ )
- Oxford Dictionary of English (aka NODE), 2d ed.
- O'Reilly Default Stylesheet, http://www.oreilly.com/oreilly/author/stylesheet.html
- Unicode Consortium Glossary, http://unicode.org/glossary/
- W3C XML Recommendation, http://www.w3.org/TR/xml/
- 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: [...].
Appendix A: 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
- 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