Guide for Technical Proof-Readers We are sending you one or more chapters of the Guidelines to read and check before we publish the Guidelines this fall. We are sending each chapter to at least two readers: one who served on the work group or working committee responsible for the material, and one 'external' reader. You provide the last bulwark against errors in the published version of the Guidelines. Please help us by making an active effort to locate and help fix problems. Check the entire chapter for technical consistency with itself and with the rest of the guidelines. If you served on the work group, please check in particular that any changes to the chapter's technical content have not rendered the material unusable or unacceptable to its intended users. (This is not, however, the time to reopen old debates about the material.) If a chapter defines a tag set, it should say somewhere (usually near the beginning or near the end) what file its tag set is in, and how the tag set is selected. (N.B. 'selected' not 'invoked'.) A simple example should be given, showing a user's DTD subset with the required entity declaration. Check the entity name for consistency with the name used in chapter ST. Some sections comprise conventional prose paragraphs; some introduce one or more SGML elements. The latter almost invariably follow the same structural pattern: 1 an introductory paragraph (or two) identifying the topic 2 a list of relevant elements 3 a 'commentary section' of several paragraphs with usage notes, commentary, examples, and cross-references to other relevant portions of the Guidelines 4 a DTD fragment with the formal declarations for (some of) the elements Each of these areas should be checked for characteristic problems. Check each introductory paragraph to ensure that: - it is short (a sentence or two often suffices --- don't let it swell to more than half a page in any case) - it is clear Check each tag list for: - correct presentation of the generic identifiers - clarity of the description (n.b. there is only one description for an element; it should make sense in all contexts where it is used, but cannot be tailored for any one context) - suitable choice of attributes for inclusion (not all attributes need be listed explicitly in the tag list, but if the prose talks a lot about the usage of a particular attribute, it should be included) - suitable sequence of elements, attributes within elements, values within attributes - correct introduction of attribute values: closed sets with 'Legal values are:', open sets with 'Sample values include:' and semi-closed sets with 'Suggested values include:' --- in case of doubt, check the declaration at the end of the section to see whether an attribute has a closed, open, or semi-closed set of values Check each commentary section to see that: - each element is discussed and illustrated, or mentioned with a cross reference to its primary discussion - obvious questions about when and how to use the elements are answered Check each example for: - consistency with the declarations (i.e. hand-parse them) - consistency with the usage notes (if the notes say the attribute FOO should *always* be given a value, make sure the examples do so) - clarity of presentation (there is no hard-and-fast indentation style, but each example should make sense for itself and the examples within a chapter should not be radically inconsistent in presentation) - empty end-tags should not be used except to end 'short' elements (of no more than two lines max) Check each cross reference for: - correct target (check the target section in your complete draft to make sure it actually talks about what the cross-reference says it talks about) - reasonable punctuation (commas and periods go inside the quotation marks, question marks, etc., in or out depending on whether they are part of the title) Check each DTD fragment for: - completeness (each element described in the section should be represented either by a declaration or by a note saying where the element is declared --- the notes may be in the DTD fragment or in the accompanying prose) - syntactic correctness (the declarations should be legal SGML) - semantic correctness (the declarations should agree with the prose and the examples; the content models should be correct; the omissibility of end-tags should make sense) In addition, please note any of the following that you find: - misspellings - inconsistencies in the spelling (especially the uppercase-lowercase pattern) of gis - garbled text (this is sometimes a formatting problem and sometimes an editing problem) - text that doesn't make sense or that is easy to misconstrue - violations of house style (see below) In the reference material, please read all elements declared in your chapter(s) with special care, checking to make sure that the reference material is clear and correct. If examples are missing, please try to provide at least one, from a real document. House style represents the product of long thought, discussion, and struggle between the editors. You are welcome to suggest modifications, but don't hold your breath. The items most relevant to your task are: