Notes on House Style C. M. Sperberg-McQueen and Lou Burnard Document Number: TEI ED W11 September 14, 1992 (14:48:00) Draft September 14, 1992 (14:48:00) ABSTRACT This document describes house style rules for the preparation of the TEI Guidelines, from general points of structure down to details of spell- ing. It is intended for use by TEI participants preparing drafts and by the TEI editorial staff. This document lists some possibly contentious issues of style (in the conventional publishing sense) and states the agreement of MSM and LB concerning them. All drafts are to be brought into conformance with this style. 1 TAG USAGE Choices of Tags In marking various special types of term or phrase, be consistent: tags: For tag names in continuous prose, in general use the tag -- if there is no reference to the abstract element type, but just an example of a tag instance, then use instead. The presence of attribute value specs is prima facie evidence that the phrase in ques- tion is a not a , as is presence of a slash before the name to simulate an end-tag. For tags in examples, use the normal literal string surrounded by an XMP tag and a CDATA marked section. attribute names: In continuous prose, use the tag. In examples this shouldn't be necessary. markup declarations: There is an tag, but most usages will require only an . tables of contents: tag any sample tables of contents as simple lists, not numbered (ordered) or unordered (bulleted) lists. Give section numbers explicitly. lists of terms: most lists of terms and headed lists should be tagged as glossary lists using the tag. Consistent use of the and tags will allow better auto- matic generation of indices. Tag Documentation Crystals In drafting content for the tag documentation crystals, note the fol- lowing: element description: a VP, with the implied subject "This element ...", not "This tag ... ". Thus begin the with "contains ...", "specifies ...", "is used to ...", not "marks ...", "indicates ...", etc. attribute description: similarly, a VP with implied subject "This attribute ..." valdesc: an NP in apposition, or an S. Not a VP. Positioning In general: use "tight" positioning. Tags which delimit structural units (

, etc.) may be on lines of their own. If they are not, they should be placed so they abut the content they delimit: the start tag should not be followed by space, the end tag should not be preceded by space. This has in the past been a particular problem for: * the

and
tags (definition-list term and definition-list definition) * the and tags (glossary-list term and glossary-list defini- tion) * the and tags (quote, end-quote) Tags which delimit sub-paragraph-level phrases should abut their con- tent: no space after the start tag, no space before the end tag. Section tags (

etc.) should abut the title of the section.(1) All section headings should be consistently numbered and titled. 2 SPELLINGS AND PUNCTUATION In general, follow Webster's 3d in cases of dispute. Specific rules: * DTD not dtd * BNF not bnf * favor, labor, color not favour, labour, colour (but try to avoid these words in the first place) * use the forms -ize, -izes, -ization, not -ise, -ises, -isation. But "analysis" and "analyse", not -yze. * Double spaces go after sentence endings and after colons. Also after the enumerator of a section heading, if the enumerator ends in a stop. * In examples, SGML keywords (entity, doctype, system, pcdata) should be all caps. * Run-on lists take the form "a, b, c, and d", or "a, b, c, etc.", not "a, b, c and d" and not "a, b, c etc." * Full stop after "etc." ------------------------- (1) Waterloo GML, at least, has serious trouble with spaces following section titles. Draft September 14, 1992 (14:48:00)