Style Guide for Editing the TEI Guidelines


Contents

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.)

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
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.

Appendix A: Some other (mostly superseded) documents on the topic of style

  1. TEI ED W9 Points of Style For Drafts of TEI Guidelines 2 Mar 1990 in Waterloo Script format
  2. Notes on House Style TEI ED W11 14 Sep 1992 in Waterloo script formatted text
  3. TEI ED W55 Form for Draft Chapters of the TEI Guidelines 5 june 1996 in TEI P2 format in HTML format in ODD format
  4. TEI ED W57 Procedures for Correcting Errors in the TEI Guidelines July 23, 1994 in TEI P2 format in HTML format