Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
authorTravis Leithead
Mon, 05 May 2014 13:31:15 -0700
changeset 613 a5ef91af0785
parent 612 9bf48167060a
child 614 9dc74ec13aea
Fix 25559 - Spec readability: Drop some obvious "stylistic conventions" definitions (Notes, Warnings, Examples)
* Issues moved into its own section.
* Minor editorial pass on existing prose in this section.
html/DOM3-Events.html
--- a/html/DOM3-Events.html	Tue Apr 29 17:27:32 2014 -0700
+++ b/html/DOM3-Events.html	Mon May 05 13:31:15 2014 -0700
@@ -261,23 +261,28 @@
 
 		<section id="style-conventions">
 			<h2>Stylistic Conventions</h2>
-			<p>The following stylistic conventions are followed in this specification, per the <a href="http://www.w3.org/People/Schepers/spec-conventions.html">Proposed W3C Specification
-				Conventions</a>:</p>
+			<p>This specification follows the <a href="http://www.w3.org/People/Schepers/spec-conventions.html">Proposed W3C Specification
+				Conventions</a>, with the following supplemental additions:</p>
 
 			<dl>
+				<!-- This is de-facto stylistic convention used in other W3C specs (e.g. DOM4/HTML5/etc.):
 				<dt>Keywords or values</dt>
 				<dd><code>This is a keyword or value</code></dd>
-
+				-->
+				
+				<!-- This is not stylistically unique in the document: 
 				<dt>Event types</dt>
 				<dd><code class="eventtype">This is an event type</code></dd>
-
+				-->
+				
 				<dt>Key and character values</dt>
-				<dd>
-					This is a key name: <code class="key">'='</code> (e.g., the value of <a href="#widl-KeyboardEvent-key"><code>KeyboardEvent.key</code></a>).
-					This is the equivalent character value: <code class="char">'\u003d'</code>.
-					This is a glyph that represents that same character value: <code class="glyph">'='</code>.
-				</dd>
-
+				<dd><ul>
+					<li>Names of key values are shown as: <code class="key">'='</code> (e.g., the value of <a href="#widl-KeyboardEvent-key"><code>KeyboardEvent.key</code></a>).
+					<li>Character values of keys are shown as: <code class="char">'\u003d'</code>.
+					<li>Glyphs representing character values are shown as: <code class="glyph">'='</code>.
+				</ul></dd>
+
+				<!-- The following are self-describing:
 				<dt>Glossary definitions</dt>
 				<dd><span class="def">This is a link to a definition in the glossary</span></dd>
 
@@ -294,12 +299,15 @@
 						<p>This is an example.</p>
 					</div>
 				</dd>
+				-->
 
 				<!-- [Not current used in this document] <dt>Features at risk</dt>
 					<dd><p class="atrisk">This is a feature at risk, which is likely to be removed from the specification.</p></dd>-->
 
+				<!-- This is a self-describing stylistic convention. However, it really belongs in its own section for issues:
 				<dt>Spec Issues</dt>
 				<dd><p class="issue">This is an open issue.</p></dd>
+				-->
 			</dl>
 
 			<p>In addition, certain terms are used in this specification with particular meanings.  The term <q>implementation</q> applies to a browser, content authoring tool,
@@ -309,6 +317,11 @@
 		</section>  <!-- style-conventions -->
 	</section>  <!-- dom-events -->
 
+	<section id="issues">
+		<h1>Issues</h1>
+		
+		<p class="issue">Open issues in this specification are called out using this convention.</p>
+	</section>
 	<!-- Section 2: Glossary  ========================================================-->
 	<section id="glossary">
 		<h1>Glossary</h1>