Notes on House Style <author>C. M. Sperberg-McQueen and Lou Burnard <docnum>TEI ED W11 <date>&docdate. </titlep> <!> <abstract> This document describes house style rules for the preparation of the TEI Guidelines, from general points of structure down to details of spelling. It is intended for use by TEI participants preparing drafts and by the TEI editorial staff. </abstract> <toc> </frontm> <!> <!> <body> 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. <!> <h1>Tag Usage <h2>Choices of Tags <!> In marking various special types of term or phrase, be consistent: <gl> <gt>tags <gd>For tag names in continuous prose, in general use the <gi>gi</gi> tag -- if there is no reference to the abstract element type, but just an example of a tag <emph>instance</emph>, then use <gi>tag</gi> instead. The presence of attribute value specs is prima facie evidence that the phrase in question is a <gi>tag</gi> not a <gi>gi</gi>, 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. <gt>attribute names <gd>In continuous prose, use the <gi>att</gi> tag. In examples this shouldn't be necessary. <gt>markup declarations <gd>There is an <gi>mdecl</gi> tag, but most usages will require only an <gi>xmp</gi>. <gt>tables of contents <gd>tag any sample tables of contents as simple lists, not numbered (ordered) or unordered (bulleted) lists. Give section numbers explicitly. <gt>lists of terms <gd>most lists of terms and headed lists should be tagged as glossary lists using the <gi>gl</gi> tag. </gl> Consistent use of the <gi>tag</gi> and <gi>attribute</gi> tags will allow better automatic generation of indices. <!> <h2>Tag Documentation Crystals <p>In drafting content for the tag documentation crystals, note the following: <gl> <gt>element description: a VP, with the implied subject <q>This element ...</q>, <emph>not</emph> <q>This tag ... </q>. Thus begin the <gi>desc</gi> with <q>contains ...</q>, <q>specifies ...</q>, <q>is used to ...</q>, not <q>marks ...</q>, <q>indicates ...</q>, etc. <gt>attribute description <gd>similarly, a VP with implied subject <q>This attribute ...</q> <gt>valdesc <gd>an NP in apposition, or an S. Not a VP. </gl> <!> <h2>Positioning In general: use <q>tight</q> positioning. Tags which delimit structural units (<tag>p</tag>, 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: <ul> <li>the <tag>dt</tag> and <tag>dd</tag> tags (definition-list term and definition-list definition) <li>the <tag>gt</tag> and <tag>gd</tag> tags (glossary-list term and glossary-list definition) <li>the <tag>q</tag> and <tag>/q</tag> tags (quote, end-quote) </ul> <p> Tags which delimit sub-paragraph-level phrases should abut their content: no space after the start tag, no space before the end tag. <p>Section tags (<tag>h1</tag> etc.) should abut the title of the section.<fn>Waterloo GML, at least, has serious trouble with spaces following section titles.</fn> All section headings should be consistently numbered and titled. <!> <!> <h1>Spellings and punctuation In general, follow Webster's 3d in cases of dispute. Specific rules: <ul> <li>DTD not dtd <li>BNF not bnf <li>favor, labor, color not favour, labour, colour (but try to avoid these words in the first place) <li>use the forms -ize, -izes, -ization, not -ise, -ises, -isation. But <q>analysis</q> and <q>analyse</q>, not -yze. <li>Double spaces go after sentence endings and after colons. Also after the enumerator of a section heading, if the enumerator ends in a stop. <li>In examples, SGML keywords (entity, doctype, system, pcdata) should be all caps. <li>Run-on lists take the form <q>a, b, c, and d</q>, or <q>a, b, c, etc.</q>, not <q>a, b, c and d</q> and not <q>a, b, c etc.</q> <li>Full stop after <q>etc.</q> </ul> <!> </body> <!> </gdoc>

.sr docfile = &sysfnam. ;.sr docversion = 'Draft';.im teigmlp1 Notes on House Style <author>C. M. Sperberg-McQueen and Lou Burnard <docnum>TEI ED W11 <date>&docdate. </titlep> <!> <abstract> This document describes house style rules for the preparation of the TEI Guidelines, from general points of structure down to details of spelling. It is intended for use by TEI participants preparing drafts and by the TEI editorial staff. </abstract> <toc> </frontm> <!> <!> <body> 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. <!> <h1>Tag Usage <h2>Choices of Tags <!> In marking various special types of term or phrase, be consistent: <gl> <gt>tags <gd>For tag names in continuous prose, in general use the <gi>gi</gi> tag -- if there is no reference to the abstract element type, but just an example of a tag <emph>instance</emph>, then use <gi>tag</gi> instead. The presence of attribute value specs is prima facie evidence that the phrase in question is a <gi>tag</gi> not a <gi>gi</gi>, 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. <gt>attribute names <gd>In continuous prose, use the <gi>att</gi> tag. In examples this shouldn't be necessary. <gt>markup declarations <gd>There is an <gi>mdecl</gi> tag, but most usages will require only an <gi>xmp</gi>. <gt>tables of contents <gd>tag any sample tables of contents as simple lists, not numbered (ordered) or unordered (bulleted) lists. Give section numbers explicitly. <gt>lists of terms <gd>most lists of terms and headed lists should be tagged as glossary lists using the <gi>gl</gi> tag. </gl> Consistent use of the <gi>tag</gi> and <gi>attribute</gi> tags will allow better automatic generation of indices. <!> <h2>Tag Documentation Crystals <p>In drafting content for the tag documentation crystals, note the following: <gl> <gt>element description: a VP, with the implied subject <q>This element ...</q>, <emph>not</emph> <q>This tag ... </q>. Thus begin the <gi>desc</gi> with <q>contains ...</q>, <q>specifies ...</q>, <q>is used to ...</q>, not <q>marks ...</q>, <q>indicates ...</q>, etc. <gt>attribute description <gd>similarly, a VP with implied subject <q>This attribute ...</q> <gt>valdesc <gd>an NP in apposition, or an S. Not a VP. </gl> <!> <h2>Positioning In general: use <q>tight</q> positioning. Tags which delimit structural units (<tag>p</tag>, 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: <ul> <li>the <tag>dt</tag> and <tag>dd</tag> tags (definition-list term and definition-list definition) <li>the <tag>gt</tag> and <tag>gd</tag> tags (glossary-list term and glossary-list definition) <li>the <tag>q</tag> and <tag>/q</tag> tags (quote, end-quote) </ul> <p> Tags which delimit sub-paragraph-level phrases should abut their content: no space after the start tag, no space before the end tag. <p>Section tags (<tag>h1</tag> etc.) should abut the title of the section.<fn>Waterloo GML, at least, has serious trouble with spaces following section titles.</fn> All section headings should be consistently numbered and titled. <!> <!> <h1>Spellings and punctuation In general, follow Webster's 3d in cases of dispute. Specific rules: <ul> <li>DTD not dtd <li>BNF not bnf <li>favor, labor, color not favour, labour, colour (but try to avoid these words in the first place) <li>use the forms -ize, -izes, -ization, not -ise, -ises, -isation. But <q>analysis</q> and <q>analyse</q>, not -yze. <li>Double spaces go after sentence endings and after colons. Also after the enumerator of a section heading, if the enumerator ends in a stop. <li>In examples, SGML keywords (entity, doctype, system, pcdata) should be all caps. <li>Run-on lists take the form <q>a, b, c, and d</q>, or <q>a, b, c, etc.</q>, not <q>a, b, c and d</q> and not <q>a, b, c etc.</q> <li>Full stop after <q>etc.</q> </ul> <!> </body> <!> </gdoc>