[html5] r1805 - [] (0) URLification: mention that the term 'URL' isn't the same as 3986 would ha [...]

whatwg at whatwg.org whatwg at whatwg.org
Thu Jun 26 02:33:50 PDT 2008


Author: ianh
Date: 2008-06-26 02:33:49 -0700 (Thu, 26 Jun 2008)
New Revision: 1805

Modified:
   index
   source
Log:
[] (0) URLification: mention that the term 'URL' isn't the same as 3986 would have us believe; URLify <datagrid> and the main 'command' section.

Modified: index
===================================================================
--- index	2008-06-25 22:08:08 UTC (rev 1804)
+++ index	2008-06-26 09:33:49 UTC (rev 1805)
@@ -25,7 +25,7 @@
 
    <h1 id=html-5>HTML 5</h1>
 
-   <h2 class="no-num no-toc" id=draft>Draft Recommendation — 25 June
+   <h2 class="no-num no-toc" id=draft>Draft Recommendation — 26 June
     2008</h2>
 
    <p>You can take part in this work. <a
@@ -2716,6 +2716,12 @@
      href="#refsRFC3987">[RFC3987]</a>
   </ul>
 
+  <p class=note>The term "URL" in this specification is used in a manner
+   distinct from the precise technical meaning it is given in RFC 3986.
+   Readers familiar with that RFC will find it easier to read <em>this</em>
+   specification if they pretend the term "URL" as used herein is really
+   called something else altogether.
+
   <h4 id=parsing0><span class=secno>2.3.2 </span>Parsing URLs</h4>
 
   <p>To <dfn id=parse0>parse a URL</dfn> <var title="">url</var> into its
@@ -25496,8 +25502,7 @@
 
   <p>The <dfn id=src12 title=dom-event-source-src><code>src</code></dfn> DOM
    attribute must <a href="#reflect">reflect</a> the content attribute of the
-   same name.</p>
-  <!-- XXXURL XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \(URI\|IRI\|URL\) -->
+   same name.
 
   <h3 id=interactive-elements><span class=secno>4.11 </span>Interactive
    elements</h3>
@@ -25891,13 +25896,12 @@
 
    <dt><dfn id=getrowimage
     title=dom-provider-getRowImage><code>getRowImage(<var
-    title="">row</var>)</code></dfn></dt>
-   <!-- XXXURL just say "the URL of" -->
+    title="">row</var>)</code></dfn>
 
-   <dd>Must return a URI to an image that represents row <var
-    title="">row</var>, or the empty string if there is no applicable image.
-    May be omitted if no rows have associated images. If the value that this
-    method would return changes, the <code><a
+   <dd>Must return a <a href="#url">URL</a> giving the address of an image
+    that represents row <var title="">row</var>, or the empty string if there
+    is no applicable image. May be omitted if no rows have associated images.
+    If the value that this method would return changes, the <code><a
     href="#datagrid0">datagrid</a></code>'s update methods must be called to
     update the row in question.
 
@@ -26230,7 +26234,11 @@
   <p>The behavior of the default data provider depends on the nature of the
    first element child of the <code><a href="#datagrid0">datagrid</a></code>.
 
-  <dl class=switch>
+  <dl
+   class=switch><!-- XXX some of these entries say "the method must return" and
+   other say "the characteristic must be"; this should be rationalized
+   -->
+
    <dt>While the first element child is a <code><a
     href="#table">table</a></code> element
 
@@ -26367,18 +26375,18 @@
     <p class=note>The <code>colspan</code> and <code>rowspan</code>
      attributes are <a href="#ignored" title=ignore>ignored</a> by this
      algorithm.</p>
-    <!-- XXXURL take the string from the <img> and absolutify it and return that. -->
-    
+
     <p><strong><code title=dom-provider-getRowImage><a
      href="#getrowimage">getRowImage(<var
-     title="">i</var>)</a></code></strong>: If the row's first cell's element
-     has an <code><a href="#img">img</a></code> element child, then the URI
-     of the row's image is the URI of the first <code><a
-     href="#img">img</a></code> element child of the row's first cell's
-     element. Otherwise, the URI of the row's image is the empty string.</p>
-    <!-- XXX well. that sentence could
-    have gone better, that's for sure. -->
-    
+     title="">i</var>)</a></code></strong>: The <a href="#url">URL</a> of the
+     row's image is the <a href="#absolute">absolute URL</a> obtained by <a
+     href="#resolve" title="resolve a url">resolving</a> the value of the
+     <code title=attr-img-src><a href="#src">src</a></code> attribute of the
+     first <code><a href="#img">img</a></code> element child of the row's
+     first cell's element, if there is one and resolving its attribute is
+     successful. Otherwise, the <a href="#url">URL</a> of the row's image is
+     the empty string.</p>
+
     <p><strong><code title=dom-provider-getRowMenu><a
      href="#getrowmenu">getRowMenu(<var
      title="">i</var>)</a></code></strong>: If the row's first cell's element
@@ -26621,17 +26629,21 @@
      <var title="">position</var>)</a></code> must return <var
      title="">position</var>. (The generic default data provider does not
      support sorting the data grid.)</p>
-    <!-- XXXURL absolutify the URL here -->
+
     <p><code title=dom-provider-getRowImage><a
      href="#getrowimage">getRowImage(<var title="">i</var>)</a></code> must
-     return the URI of the image given by the first <code><a
-     href="#img">img</a></code> element descendant (in the real DOM) of the
-     row's element, that is not also a descendant of another element in the
-     filtered view that is a descendant of the row's element.</p>
+     return the <a href="#absolute">absolute URL</a> obtained from <a
+     href="#resolve" title="resolve a url">resolving</a> the value of the
+     <code title=attr-img-src><a href="#src">src</a></code> attribute of the
+     first <code><a href="#img">img</a></code> element descendant (in the
+     real DOM) of the row's element, that is not also a descendant of another
+     element in the filtered view that is a descendant of the row's element,
+     if such an element exists and resolving its attribute is successful.
+     Otherwise, it must return the empty string.</p>
 
-    <div class=example> <!-- XXXURL change to URL -->
+    <div class=example>
      <p>In the following example, the row with path "1,0" returns
-      "http://example.com/a" as its image URI, and the other rows (including
+      "http://example.com/a" as its image URL, and the other rows (including
       the row with path "1") return the empty string:</p>
 
      <pre><datagrid>
@@ -27139,20 +27151,20 @@
    provide the user with a method for requesting that the row be
    deleted.</dd>
 -->
-   <!-- XXXURL change to URL? -->
 
-   <dt>To obtain a URI to an image representing a row</dt>
-   <!-- XXXURL define how to absolutify -->
+   <dt>To obtain a <a href="#url">URL</a> identifying an image representing a
+    row
 
    <dd>Invoke the <code title=dom-provider-getRowImage><a
     href="#getrowimage">getRowImage()</a></code> method with a <code><a
     href="#rowspecification">RowSpecification</a></code> object representing
-    the row in question. The return value is a string representing a <a
-    href="#valid">valid URL</a> to an image. Relative URIs must be
-    interpreted relative to the <code><a
-    href="#datagrid0">datagrid</a></code>'s <span title="element's base
-    URI">base URI</span>. If the method returns the empty string, null, or if
-    the method is not defined, then the row has no associated image.
+    the row in question. The return value is a <a href="#url">URL</a>.
+    Immediately <a href="#resolve" title="resolve a url">resolve</a> that URL
+    as if it came from an attribute of the <code><a
+    href="#datagrid0">datagrid</a></code> element to obtain an <a
+    href="#absolute">absolute URL</a> identifying the image that represents
+    the row. If the method returns the empty string, null, or if the method
+    is not defined, then the row has no associated image.
 
    <dt>To obtain a context menu appropriate for a particular row
 
@@ -28274,8 +28286,8 @@
 
    <dt><dfn id=icon1 title=command-facet-Icon>Icon</dfn>
 
-   <dd>A graphical image that represents the action.</dd>
-   <!-- XXXURL define it to be an asbolute URL? -->
+   <dd>An <a href="#absolute">absolute URL</a> identifying a graphical image
+    that represents the action.
 
    <dt><dfn id=hidden1 title=command-facet-HiddenState>Hidden State</dfn>
 
@@ -28296,12 +28308,11 @@
 
    <dd>Whether the command is checked or not.
 
-   <dt><dfn id=action title=command-facet-Action>Action</dfn></dt>
-   <!-- XXXURL change to URL -->
+   <dt><dfn id=action title=command-facet-Action>Action</dfn>
 
    <dd>The actual effect that triggering the command will have. This could be
-    a scripted event handler, a URI to which to navigate, or a form
-    submission.
+    a scripted event handler, a <a href="#url">URL</a> to which to <a
+    href="#navigate">navigate</a>, or a form submission.
 
    <dt><dfn id=triggers title=command-facet-Triggers>Triggers</dfn>
 
@@ -28379,6 +28390,7 @@
    title=command-facet-Hint>Hint</a>. This attribute will be shadowed by the
    <code title=dom-title><a href="#title0">title</a></code> DOM attribute on
    the <code><a href="#htmlelement">HTMLElement</a></code> interface.</p>
+  <!-- XXXURL XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \(URI\|IRI\|URL\) -->
   <!-- XXXURL "must return the absolute URL of the command's icon"? -->
 
   <p>The <dfn id=icon2 title=dom-command-ro-icon><code>icon</code></dfn>

Modified: source
===================================================================
--- source	2008-06-25 22:08:08 UTC (rev 1804)
+++ source	2008-06-26 09:33:49 UTC (rev 1805)
@@ -959,7 +959,13 @@
 
   </ul>
 
+  <p class="note">The term "URL" in this specification is used in a
+  manner distinct from the precise technical meaning it is given in
+  RFC 3986. Readers familiar with that RFC will find it easier to read
+  <em>this</em> specification if they pretend the term "URL" as used
+  herein is really called something else altogether.</p>
 
+
   <h4>Parsing URLs</h4>
 
   <p>To <dfn>parse a URL</dfn> <var title="">url</var> into its
@@ -23190,7 +23196,6 @@
   same name.</p>
 
 
-  <!-- XXXURL XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \(URI\|IRI\|URL\) -->
 
 
   <h3 id="interactive-elements">Interactive elements</h3>
@@ -23535,13 +23540,12 @@
 
    <dt><dfn title="dom-provider-getRowImage"><code>getRowImage(<var title="">row</var>)</code></dfn></dt>
 
-   <!-- XXXURL just say "the URL of" -->
-   <dd>Must return a URI to an image that represents row <var
-   title="">row</var>, or the empty string if there is no applicable
-   image. May be omitted if no rows have associated images. If the
-   value that this method would return changes, the
-   <code>datagrid</code>'s update methods must be called to update the
-   row in question.</dd>
+   <dd>Must return a <span>URL</span> giving the address of an image
+   that represents row <var title="">row</var>, or the empty string if
+   there is no applicable image. May be omitted if no rows have
+   associated images. If the value that this method would return
+   changes, the <code>datagrid</code>'s update methods must be called
+   to update the row in question.</dd>
 
    <dt><dfn title="dom-provider-getRowMenu"><code>getRowMenu(<var title="">row</var>)</code></dfn></dt>
 
@@ -23812,6 +23816,10 @@
 
   <dl class="switch">
 
+   <!-- XXX some of these entries say "the method must return" and
+   other say "the characteristic must be"; this should be rationalized
+   -->
+
    <dt>While the first element child is a <code>table</code> element</dt>
 
    <dd>
@@ -23939,14 +23947,15 @@
     attributes are <span title="ignore">ignored</span> by this
     algorithm.</p>
 
-    <!-- XXXURL take the string from the <img> and absolutify it and return that. -->
     <p><strong><code title="dom-provider-getRowImage">getRowImage(<var
-    title="">i</var>)</code></strong>: If the row's first cell's
-    element has an <code>img</code> element child, then the URI of the
-    row's image is the URI of the first <code>img</code> element child
-    of the row's first cell's element. Otherwise, the URI of the row's
-    image is the empty string.</p><!-- XXX well. that sentence could
-    have gone better, that's for sure. -->
+    title="">i</var>)</code></strong>: The <span>URL</span> of the
+    row's image is the <span>absolute URL</span> obtained by <span
+    title="resolve a url">resolving</span> the value of the <code
+    title="attr-img-src">src</code> attribute of the first
+    <code>img</code> element child of the row's first cell's element,
+    if there is one and resolving its attribute is
+    successful. Otherwise, the <span>URL</span> of the row's image is
+    the empty string.</p>
 
     <p><strong><code title="dom-provider-getRowMenu">getRowMenu(<var
     title="">i</var>)</code></strong>: If the row's first cell's
@@ -24196,19 +24205,20 @@
     return <var title="">position</var>. (The generic default data
     provider does not support sorting the data grid.)</p>
 
-    <!-- XXXURL absolutify the URL here -->
     <p><code title="dom-provider-getRowImage">getRowImage(<var
-    title="">i</var>)</code> must return the URI of the image given by
+    title="">i</var>)</code> must return the <span>absolute URL</span>
+    obtained from <span title="resolve a url">resolving</span> the
+    value of the <code title="attr-img-src">src</code> attribute of
     the first <code>img</code> element descendant (in the real DOM) of
     the row's element, that is not also a descendant of another
     element in the filtered view that is a descendant of the row's
-    element.</p>
+    element, if such an element exists and resolving its attribute is
+    successful. Otherwise, it must return the empty string.</p>
 
     <div class="example">
 
-     <!-- XXXURL change to URL -->
      <p>In the following example, the row with path "1,0" returns
-     "http://example.com/a" as its image URI, and the other rows
+     "http://example.com/a" as its image URL, and the other rows
      (including the row with path "1") return the empty string:</p>
 
      <pre><datagrid>
@@ -24737,17 +24747,17 @@
    deleted.</dd>
 -->
 
-   <!-- XXXURL change to URL? -->
-   <dt>To obtain a URI to an image representing a row</dt>
+   <dt>To obtain a <span>URL</span> identifying an image representing a row</dt>
 
-   <!-- XXXURL define how to absolutify -->
    <dd>Invoke the <code
    title="dom-provider-getRowImage">getRowImage()</code> method with a
    <code>RowSpecification</code> object representing the row in
-   question. The return value is a string representing a <span>valid URL</span> to an image. Relative URIs must be interpreted relative to the
-   <code>datagrid</code>'s <span title="element's base URI">base
-   URI</span>. If the method returns the empty string, null, or if the
-   method is not defined, then the row has no associated image.</dd>
+   question. The return value is a <span>URL</span>. Immediately <span
+   title="resolve a url">resolve</span> that URL as if it came from an
+   attribute of the <code>datagrid</code> element to obtain an
+   <span>absolute URL</span> identifying the image that represents the
+   row. If the method returns the empty string, null, or if the method
+   is not defined, then the row has no associated image.</dd>
 
    <dt>To obtain a context menu appropriate for a particular row</dt>
 
@@ -25285,7 +25295,8 @@
 
   <p>The <dfn title="attr-command-icon"><code>icon</code></dfn>
   attribute gives a picture that represents the command. If the
-  attribute is specified, the attribute's value must contain a <span>valid URL</span>.</p>
+  attribute is specified, the attribute's value must contain a
+  <span>valid URL</span>.</p>
 
   <p>The <dfn title="attr-command-hidden"><code>hidden</code></dfn>
   attribute is a <span>boolean attribute</span> that, if present,
@@ -25819,7 +25830,8 @@
 
    <dt><dfn title="command-facet-Icon">Icon</dfn></dt>
 
-   <dd>A graphical image that represents the action.</dd> <!-- XXXURL define it to be an asbolute URL? -->
+   <dd>An <span>absolute URL</span> identifying a graphical image that
+   represents the action.</dd>
 
    <dt><dfn title="command-facet-HiddenState">Hidden State</dfn></dt>
 
@@ -25842,10 +25854,9 @@
 
    <dt><dfn title="command-facet-Action">Action</dfn></dt>
 
-   <!-- XXXURL change to URL -->
    <dd>The actual effect that triggering the command will have. This
-   could be a scripted event handler, a URI to which to navigate, or a
-   form submission.</dd>
+   could be a scripted event handler, a <span>URL</span> to which to
+   <span>navigate</span>, or a form submission.</dd>
 
    <dt><dfn title="command-facet-Triggers">Triggers</dfn></dt>
 
@@ -25925,6 +25936,9 @@
   shadowed by the <code title="dom-title">title</code> DOM attribute
   on the <code>HTMLElement</code> interface.</p>
 
+
+  <!-- XXXURL XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \(URI\|IRI\|URL\) -->
+
   <!-- XXXURL "must return the absolute URL of the command's icon"? -->
   <p>The <dfn title="dom-command-ro-icon"><code>icon</code></dfn>
   attribute must return an absolute URI to the command's <span




More information about the Commit-Watchers mailing list