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.
--- 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>