Index: source
===================================================================
--- source	(revision 1231)
+++ source	(revision 1232)
@@ -8512,7 +8512,7 @@
   </div>
 
 
-  <h4>The <dfn><code>m</code></dfn> element</h4>
+  <h4>The <dfn><code>mark</code></dfn> element</h4>
 
   <dl class="element">
    <dt>Categories</dt>
@@ -8527,11 +8527,49 @@
    <dd>No difference from <code>HTMLElement</code>.</dd>
   </dl>
 
-  <p class="big-issue">This section has a large number of outstanding
-  comments and will likely be rewritten or removed from the spec.</p>
+  <p>The <code>mark</code> element represents a run of text in one
+  document marked or highlighted for reference purposes, due to its
+  relevance in another context. When used in a quotation or other
+  block of text referred to from the prose, it indicates a highlight
+  that was not originally present but which has been added to bring
+  the reader's attention to a part of the text that might not have
+  been considered important by the original author when the block was
+  originally written, but which is now under previously unexpected
+  scrutiny. When used in the main prose of a document, it indicates a
+  part of the document that has been highlighted due to its likely
+  relevance to the user's current activity.</p>
+
+  <p class="big-issue">The rendering section will eventually suggest
+  that user agents provide a way to let users jump between
+  <code>mark</code> elements. Suggested rendering is a neon yellow
+  background highlight, though UAs maybe should allow this to be
+  toggled.</p>
 
-  <p>The <code>m</code> element represents a run of text marked or
-  highlighted.</p>
+  <div class="example">
+   <p>This example shows how the <code>mark</code> example can be used
+   to bring attention to a particular part of a quotation:</p>
+   <pre>&lt;p lang="en-US">Consider the following quote:&lt;/p>
+&lt;blockquote lang="en-GB">
+ &lt;p>Look around and you will find, no-one's really
+ &lt;mark>colour&lt;/mark> blind.&lt;/p>
+&lt;/blockquote>
+&lt;p lang="en-US">As we can tell from the &lt;em>spelling&lt;/em> of the word,
+the person writing this quote is clearly not American.&lt;/p></pre>
+  </div>
+
+  <div class="example">
+
+   <p>Another example of the <code>mark</code> element is highlighting
+   parts of a document that are matching some search string. If
+   someone looked at a document, and the server knew that the user was
+   searching for the word "kitten", then the server might return the
+   document with one paragraph modified as follows:</p>
+
+   <pre>&lt;p>I also have some &lt;mark>kitten&lt;/mark>s who are visiting me
+these days. They're really cute. I think they like my garden! Maybe I
+should adopt a &lt;mark>kitten&lt;/mark>.&lt;/p></pre>
+
+  </div>
 
   <div class="example">
 
@@ -8541,21 +8579,83 @@
    <pre>&lt;p>The highlighted part below is where the error lies:&lt;/p>
 &lt;pre>&lt;code>var i: Integer;
 begin
-   i := &lt;m>1.1&lt;/m>;
+   i := &lt;mark>1.1&lt;/mark>;
 end.&lt;/code>&lt;/pre></pre>
 
-   <p>Another example of the <code>m</code> element is highlighting
-   parts of a document that are matching some search string. If
-   someone looked at a document, and the server knew that the user was
-   searching for the word "kitten", then the server might return the
-   document with one paragraph modified as follows:</p>
+  </div>
+
+  <div class="example">
+
+   <p>This is another example showing the use of <code>mark</code> to
+   highlight a part of quoted text that was originally not
+   emphasised. In this example, common typographic conventions have
+   led the author to explicitly style <code>mark</code> elements in
+   quotes to render in italics.</p>
+
+   <pre>&lt;article>
+ &lt;style>
+  blockquote mark, q mark {
+    font: inherit; font-style: italic;
+    text-decoration: none;
+    background: transparent; color: inherit;
+  }
+  .bubble em {
+    font: inherit; font-size: larger;
+    text-decoration: underline;
+  }
+ &lt;/style>
+ &lt;h1>She knew&lt;/h1>
+ &lt;p>Did you notice the subtle joke in the joke on panel 4?&lt;/p>
+ &lt;blockquote>
+  &lt;p class="bubble">I didn't &lt;em>want&lt;/em> to believe. &lt;mark>Of course
+  on some level I realized it was a known-plaintext attack.&lt;/mark> But I
+  couldn't admit it until I saw for myself.&lt;/p>
+ &lt;/blockquote>
+ &lt;p>(Emphasis mine.) I thought that was great. It's so pedantic, yet it
+ explains everything neatly.&lt;/p>
+&lt;/article></pre>
 
-   <pre>&lt;p>I also have some &lt;m>kitten&lt;/m>s who are visiting me
-these days. They're really cute. I think they like my garden!&lt;/p></pre>
+   <p>Note, incidentally, the distinction between the <code>em</code>
+   element in this example, which is part of the original text being
+   quoted, and the <code>mark</code> element, which is highlighting a
+   part for comment.</p>
+
+  </div>
+
+  <div class="example">
+
+   <p>The following example shows the difference between denoting the
+   <em>importance</em> of a span of text (<code>strong</code>) as
+   opposed to denoting the <em>relevance</em> of a span of text
+   (<code>mark</code>). It is an extract from a textbook, where the
+   extract has had the parts relevant to the exam highlighted. The
+   safety warnings, important though they may be, are apparently not
+   relevant to the exam.</p>
+
+   <pre>&lt;h3>Wormhole Physics Introduction&lt;/h3>
+
+&lt;p>&lt;mark>A wormhole in normal conditions can be held open for a
+maximum of just under 39 minutes.&lt;/mark> Conditions that can increase
+the time include a powerful energy source coupled to one or both of
+the gates connecting the wormhole, and a large gravity well (such as a
+black hole).&lt;/p>
+
+&lt;p>&lt;mark>Momentum is preserved across the wormhole. Electromagnetic
+radiation can travel in both directions through a wormhole,
+but matter cannot.&lt;/mark>&lt;/p>
+
+&lt;p>When a wormhole is created, a vortex normally forms.
+&lt;strong>Warning: The vortex caused by the wormhole opening will
+annihilate anything in its path.&lt;/strong> Vortexes can be avoided when
+using sufficently advanced dialing technology.&lt;/p>
+
+&lt;p>&lt;mark>An obstruction in a gate will prevent it from accepting a
+wormhole connection.&lt;/mark>&lt;/p></pre>
 
   </div>
 
 
+
   <h4>The <dfn><code>dfn</code></dfn> element</h4>
 
   <dl class="element">
@@ -9747,13 +9847,6 @@
   </div>
 
   <div class="example">
-   <p>The following would be <em>incorrect</em> usage:</p>
-   <pre>&lt;p>&lt;b>WARNING!&lt;/b> Do not frob the barbinator!&lt;/p></pre>
-   <p>In the previous example, the correct element to use would have
-   been <code>strong</code>, not <code>b</code>.</p>
-  </div>
-
-  <div class="example">
    <p>In the following example, objects in a text adventure are
    highlighted as being special by use of the <code>b</code>
    element.</p>
@@ -9782,7 +9875,14 @@
   use the <code>h1</code> to <code>h6</code> elements, stress emphasis
   should use the <code>em</code> element, importance should be denoted
   with the <code>strong</code> element, and text marked or highlighted
-  should use the <code>m</code> element.</p>
+  should use the <code>mark</code> element.</p>
+
+  <div class="example">
+   <p>The following would be <em>incorrect</em> usage:</p>
+   <pre>&lt;p>&lt;b>WARNING!&lt;/b> Do not frob the barbinator!&lt;/p></pre>
+   <p>In the previous example, the correct element to use would have
+   been <code>strong</code>, not <code>b</code>.</p>
+  </div>
 
   <p class="note">Style sheets can be used to format <code>b</code>
   elements, just like any other element can be restyled. Thus, it is
@@ -9838,6 +9938,14 @@
 
 
 
+  <h4>Usage summary</h4>
+
+  <p class="big-issue">We need to summarise the various elements, in
+  particular to distinguish b/i/em/strong/var/q/mark/cite.</p>
+
+  <!-- XXX when you do this, also reorder the elements in this section
+  to bring the related ones closer together. -->
+
 
   <h3>Edits</h3>