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)