Fix Ashok's emailed comments
authorJohn Arwe
Wed, 09 Jul 2014 17:33:31 -0400
changeset 701 d64b9d9aad22
parent 700 e530fb39738a
child 702 73a7b38f2dc6
child 704 0d93ea6c4021
Fix Ashok's emailed comments
ldp-paging.html
--- a/ldp-paging.html	Wed Jul 09 13:22:55 2014 -0400
+++ b/ldp-paging.html	Wed Jul 09 17:33:31 2014 -0400
@@ -394,7 +394,7 @@
 	
 	<dt><dfn>In-sequence page resource</dfn></dt>
 	<dd>One of a sequence of related <a title="Linked Data Platform Resource">LDPRs</a>
-	<var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>, 
+	<var>P<sub>1 (first)</sub>, P<sub>2</sub>, ...,P<sub>n (last)</sub></var>, 
 	each of which contains a subset of the state
 	of another resource <var>P</var>, called the <a>paged resource</a>.
 	For readers
@@ -408,25 +408,43 @@
 	in cases where both are mentioned in
 	close proximity.  
 	</p>
+	<p>
+	Note: page sequences are described and named with respect to how they are traversed starting from the <a>paged resource</a>,
+	with "first" being "nearest" to the <a>paged resource</a>, "last" the "furthest" from the <a>paged resource</a> (using only "forward" traversal),
+	and so on.  This <em>does not</em> imply anything more; the choice is arbitrary.
+	For example, following forward links does not imply that resources later in the sequence are newer; the forward direction might
+	correspond to moving forward or backward in time or along some other dimension, but any such relationship is server-specific
+	It is not implied by LDP Paging, 
+	absent additional concrete assertions like those defined later for LDPC representations.
+	</p>
 	<p></p></dd>
 	
 	<dt><dfn>first page link</dfn></dt>
-	<dd>A link to the first <a title="In-sequence page resource">in-sequence page resource</a>
-	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
+	<dd>A link to the first <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>1 (first)</sub></var>
+	of a <a title="Paged resource">paged resource</a> <var>P</var>.  The first page is the one that a LDP paging server
+	redirects to (<code>303</code> response) or provides the representation of (<code>2NN response</code>) in response
+	to a retrieval request for the <a>paged resource</a>'s URI; it is, in that sense, nearest to the <a>paged resource</a> <var>P</var>.
+	Syntactically, a
 	HTTP <code>Link &lt;<var>P<sub>1</sub></var>&gt;; rel='first'</code>
 	header [[!RFC5988]].
 	<p></p></dd>
 	
 	<dt><dfn>next page link</dfn></dt>
-	<dd>A link to the next <a title="In-sequence page resource">in-sequence page resource</a>
+	<dd>A link to the next <a title="In-sequence page resource">in-sequence page resource</a> 
 	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
 	HTTP <code>Link &lt;<var>P<sub>i</sub></var>&gt;; rel='next'</code>
-	header [[!RFC5988]][[!HTML5]] where the target URI is <var>P<sub>i=2...n</sub></var>.
+	header [[!RFC5988]][[!HTML5]] where 
+	the context URI identifies some <var>P<sub>i=1 (first)...n-1 (next to last)</sub></var> and
+	the target URI identifies <var>P<sub>i+1</sub></var>.
 	<p></p></dd>
 	
 	<dt><dfn>last page link</dfn></dt>
-	<dd>A link to the last <a title="In-sequence page resource">in-sequence page resource</a>
-	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
+	<dd>A link to the last <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>n (last)</sub></var>
+	of a <a title="Paged resource">paged resource</a> <var>P</var>.  
+	The last page is the page that terminates a <a>forward traversal</a> starting from 
+	the <a>first page link</a> (or from any later point in the sequence) because it contains no <a>next page link</a>;
+	it is, in that sense, furthest from the <a>paged resource</a> <var>P</var>.
+	Syntactically, a
 	HTTP <code>Link &lt;<var>P<sub>n</sub></var>&gt;; rel='last'</code>
 	header [[!RFC5988]].
 	<p></p></dd>
@@ -435,7 +453,9 @@
 	<dd>A link to the previous <a title="In-sequence page resource">in-sequence page resource</a>
 	of a <a title="Paged resource">paged resource</a> <var>P</var>.  Syntactically, a
 	HTTP <code>Link &lt;<var>P<sub>i</sub></var>&gt;; rel='prev'</code>
-	header [[!RFC5988]][[!HTML5]] where the target URI is <var>P<sub>i=1...n-1</sub></var>.
+	header [[!RFC5988]][[!HTML5]] where 
+	the context URI identifies some <var>P<sub>i=2...n (last)</sub></var> and
+	the target URI identifies <var>P<sub>i-1</sub></var>.
 	<p></p></dd>
 	
 	<dt><dfn>paging link</dfn></dt>
@@ -622,7 +642,8 @@
 	<p>
 		The new protocol does not solve the problem of migrating existing clients from the old
 		"all" to the new "first chunk" semantic; neither would a <code>303 See Other</code> redirect
-		from the old to the new URI, given the widespread historical client practice of automatically
+		from the old to the new URI, given the 
+		<a href="http://www.w3.org/2001/tag/issues.html#httpRange-14">widespread historical client practice</a> of automatically
 		following <code>303</code> redirects and treating the redirected-to resource as equivalent
 		to the original.  The safe route is to have clients explicitly tell the server that they
 		are capable of handling the "first chunk" semantic on the redirected-to URI; this is what
@@ -846,7 +867,7 @@
 		and a representation payload.
 	</p>
 	<p>
-		As was true in the <a href="#ldpp-ex-paging-303"></a> <code>303 See Other</code> approach</a>, 
+		As was true in the <a href="#ldpp-ex-paging-303"><code>303 See Other</code> approach</a>, 
 		the server includes 
 		a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
 		identifying the first page as the resource whose representation is enclosed in the response.
@@ -1016,6 +1037,46 @@
 
 </section>
 
+<section id="ldpp-ex-paging-other-links">
+<h2>Optional paging links</h2>
+
+	<p>
+		The preceding paging examples in this section have all assumed that only <a>forward traversal</a>
+		is supported by the server, to reduce complexity.
+		A server might also support <a>backward traversal</a> through its pages, and/or direct access to the 
+		<a title="first page link">first page</a> and/or <a title="last page link">last page</a> from any <a>in-sequence page resource</a>.
+		Those options would be reflected by adding some combination of the links below, 
+		or equivalent semantically equivalent syntactic variations of them, to the response messages.
+	</p>
+
+	<ul>
+	<li>
+		The <a title="first page link">first page</a>'s <a href="#ldpp-ex-paging-2nn-resp1">response message</a> might also have the following links:
+<pre class="example">
+Link: &lt;&gt;; rel='first'
+Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='last'
+</pre>
+	</li>
+	<li>
+		Any <a>in-sequence page resource</a>'s response message, including the <a title="first page link">first page</a> and the <a title="last page link">last page</a>,
+		might also have the following links:
+<pre class="example">
+Link: &lt;&gt;; rel='first'
+Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='last'
+</pre>
+	</li>
+	<li>
+		The <a title="last page link">last page</a>'s <a href="#ldpp-ex-paging-2nn-resp2">response message</a> might also have the following links:
+<pre class="example">
+Link: &lt;http://example.org/customer-relations?page1&gt;; rel='first'
+Link: &lt;http://example.org/customer-relations?page1&gt;; rel='prev'
+Link: &lt;&gt;; rel='last'
+</pre>
+	</li>
+	</ul>
+
+</section>
+
 </section> <!-- Example message exchanges -->
 
 <section id="ldppclient">
@@ -1384,6 +1445,13 @@
 		and a corresponding parameter value identical to the ETag [[!RFC7232]]
 		of the <a>paged resource</a>.
 		For example: <code>Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"</code>
+		<blockquote><em>Non-normative note:</em> 
+		If the <code>rel='canonical'; etag="..."</code> value changes as the client retrieves pages, 
+		for example the value accompanying the first page's representation is <code>rel='canonical'; etag="v1"</code> 
+		and the value accompanying the second page's representation is <code>rel='canonical'; etag="v2"</code>,
+		the client can detect that the <a>paged resource</a>'s state has changed.
+		Some clients will ignore such changes, but others may choose to react to them, for example by restarting the traversal.
+		</blockquote>
 	</h2></section>
 
 	<section id="ldpr-pagingGET-sequences-change"><h2 class="normal">
@@ -1894,6 +1962,7 @@
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140730/">Last Call Draft</a></em></blockquote> -->
 <ul>
+	<li>2014-07-09 - Fix Ashok's emailed comments (JA) </li>
 	<li>2014-07-09 - Clean up clients chapter, references, non/normative section listing in conformance, kitchen sink (JA) </li>
 	<li>2014-07-09 - Move paging example into "intro" chapter 4 (JA) </li>
 	<li>2014-07-08 - Resolve a set of editorial to-dos (JA) </li>