- From: fantasai <fantasai.lists@inkedblade.net>
- Date: Mon, 5 Sep 2016 17:36:51 -0400
- To: "www-style@w3.org" <www-style@w3.org>
A few things up front here... 1. “layouted” is not a word. The past tense of the verb “lay out” is “laid out”. 2. While turning entire sentence predicates into terminology might be the hip thing to do in some circles, in CSS we try to define individual nouns and (in some cases) verbs for cross-linking. Not only does this look less absurd to the lay person, it gives more grammatical flexibility to the referrer, focuses highlights on concept-distinguishing content words rather than their surrounding sentence-context words, reduces the need for passive construction (and thereby the wordiness of sentences in general), and reduces the effort necessary to commit terminology to memory and keep its consistent throughout the spec. For example, # A table-root element is said to be <dfn>layouted in collapsed-borders mode</dfn> is better as | The table is in <dfn>collapsed-borders mode</dfn> 3. CSS layout operates on boxes, not elements. A table-root element is not layouted. A table is laid out. The only sections of your spec that should be talking about elements are the ones discussing boxes being generated from elements, and those making comparisons or examples with HTML *elements*. See https://drafts.csswg.org/css-display/#intro 4. The format for defining values of a CSS property is <dl dfn-for="property-name" dfn-type="value"> <dt><dfn>value</dfn> <dd>... <dt><dfn>other-value</dfn> <dd>... </dl> This will facilitate correct formatting and cross-linking. Also, using <dl> instead of a bunch of mixed-up paragraphs with inline definitions makes the spec easier to scan. Unlike blog posts, which are meant to be read like normal literature, CSS specs must be designed equally for scanning and perusing. Part of this effort is in the styling (it is one of the reasons our specs don't have a “subtle” look to them), but part of it is also in how we as spec editors structure our content. 5. The word “may” MUST NOT appear in your spec except when describing optional behavior. For example, # Lengths may not be negative. should be | Negative values are invalid. or some such unequivocal statement. ~fantasai
Received on Monday, 5 September 2016 22:22:02 UTC