Move example up to full chapter, and show the evolution/composition from nothing to 303 to 2NN
authorJohn Arwe
Wed, 09 Jul 2014 11:18:31 -0400
changeset 699 69b72e31eb69
parent 698 e5ece7d79d8e
child 700 e530fb39738a
Move example up to full chapter, and show the evolution/composition from nothing to 303 to 2NN
ldp-paging.html
--- a/ldp-paging.html	Tue Jul 08 16:39:11 2014 -0400
+++ b/ldp-paging.html	Wed Jul 09 11:18:31 2014 -0400
@@ -14,7 +14,7 @@
 	TODO: Example 11 is missing ldp:contains, true?  Omit due to GET on page resource, should make it more clear.
 	TODO: Paging intro: add 3rd example showing header linkage amongst pages and (HEAD on) the base resource.
      Maybe also insert HEAD on base as new first example instead of relying on text alone.
-    TODO: Missing namespace definition clause?
+    DONE: Missing namespace definition clause?
  -->
 <html>
   <head>
@@ -289,7 +289,7 @@
 	</p>
 	<p>
 		For context and background, it could be useful to read <a href="#bib-LDP-UCR">Linked Data Platform Use Case and Requirements</a> [[LDP-UCR]] 
-		and <a href="#base-specs" class="sectionRef"></a>.
+		and <a href="#base-specs" class="sectionRef"></a>.  A detailed example is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
 	</p>
 </section>
 	
@@ -382,6 +382,7 @@
 	<a title="In-sequence page resource"><em>individual page resources</em></a>, 
 	in cases where both are mentioned in
 	close proximity.  
+	</p>
 	<p></p></dd>
 	
 	<dt><dfn>first page link</dfn></dt>
@@ -445,6 +446,7 @@
 <section id="conventions">
 <h2>Conventions Used in This Document</h2>
 
+	<p>The namespace for LDP Paging is <code>http://www.w3.org/ns/ldp#</code>.</p>
 	<p>Sample resource representations are provided in <code>text/turtle</code>
 		format [[turtle]].</p>
 	<p>Commonly used namespace prefixes:</p>
@@ -462,21 +464,26 @@
 <p>The status of the sections of Linked Data Platform Paging 1.0 (this document) is as follows:</p>
 
 <ul>
-  <li>1. Introduction: <b>non-normative</b></li>
-  <li>2. Terminology</li>
+  <li><a href="#intro" class="sectionRef"></a>: <b>non-normative</b></li>
+  <li><a href="#terms" class="sectionRef"></a></li>
 	<ul>
-	  <li>2.1 Terms re-used from the Linked Data Platform: <b>non-normative</b></li>
-	  <li>2.2 Terms normatively defined by this specification: <b>normative</b></li>
-	  <li>2.3 Conventions Used in This Document: <b>normative</b></li>
+	  <li><a href="#terms-from-ldp" class="sectionRef"></a>: <b>non-normative</b></li>
+	  <li><a href="#terms-from-paging" class="sectionRef"></a>: <b>normative</b></li>
+	  <li><a href="#conventions" class="sectionRef"></a>: <b>normative</b></li>
 	</ul>
-  <li>3. Conformance: <b>normative</b></li>
-  <li>4. Linked Data Platform Paging Clients: <b>normative</b></li>
-  <li>5. Linked Data Platform Resources: <b>normative</b></li>
-  <li>6. Linked Data Platform Containers: <b>normative</b></li>
-  <li>7. Notable information from normative references: <b>non-normative</b></li>
-  <li>A. Acknowledgements: <b>non-normative</b></li> 
-  <li>B.1 Normative references: <b>normative</b></li>
-  <li>B.2 Non-normative references: <b>non-normative</b></li>
+  <li><a href="#conformance" class="sectionRef"></a>: <b>normative</b></li>
+  <li><a href="#ldpp-ex-mx" class="sectionRef"></a>: <b>non-normative</b></li>
+  <li><a href="#ldppclient" class="sectionRef"></a>: <b>normative</b></li>
+  <li><a href="#ldpr" class="sectionRef"></a>: <b>normative</b></li>
+  <li><a href="#ldpc" class="sectionRef"></a>: <b>normative</b></li>
+  <li><a href="#base-specs" class="sectionRef"></a>: <b>non-normative</b></li>
+  <!-- TODO: figure out why next 2 do not show up in TOC or get
+       resolved as sectionrefs ... probably an unbalanced tag
+	   somewhere -->
+  <li><a href="#security" class="sectionRef"></a>: <b>non-normative</b></li> 
+  <li><a href="#acks" class="sectionRef"></a>: <b>non-normative</b></li> 
+  <li><a href="#normative-references" class="sectionRef"></a>: <b>normative</b></li>
+  <li><a href="#informative-references" class="sectionRef"></a>: <b>non-normative</b></li>
 </ul>
 
 <p>A conforming <b><dfn>LDP Paging client</dfn></b> is a conforming LDP client [[!LDP]] that follows the rules defined by LDP Paging.
@@ -485,12 +492,531 @@
 <p>A conforming <b><dfn>LDP Paging server</dfn></b> is a conforming LDP server [[!LDP]] that follows the rules defined by LDP Paging.</p>
 </section>
 
+<section class="informative" id="ldpp-ex-mx">
+<h1>Example paging message exchanges</h1>
+
+	<p>
+		Example Co.'s customer
+		relationship data is identified by the URI <code>http://example.org/customer-relations</code>,
+		and is retrievable using the same URI.
+	</p>
+
+<section id="ldpp-ex-no-paging">
+<h2>Traditional flow without paging</h2>
+
+	<p>
+		A standard HTTP client that knows nothing about LDP paging obtains a representation of the
+		resource in the usual way.
+	</p>
+
+	<em>Request</em>
+<pre class="example">GET /customer-relations HTTP/1.1
+Host: example.org
+Accept: text/turtle
+</pre>
+
+	<p>
+		The server responds with status code <code>200 OK</code> and the following representation: 
+	</p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-no-paging-resp">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "_87e52ce291112"
+Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
+
+&lt;&gt;
+   a o:CustomerRelations;
+   dcterms:title "The customer information for Example Co.";
+   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;,
+            &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 
+
+&lt;#JohnZSmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer;
+   foaf:name "John Z. Smith".
+   
+&lt;#BettyASmith&gt;
+   a foaf:Person;
+   o:status o:PreviousCustomer;
+   foaf:name "Betty A. Smith".
+ 
+ &lt;#JoanRSmith&gt;
+   a foaf:Person;
+   o:status o:PotentialCustomer;
+   foaf:name "Joan R. Smith".
+ 
+&lt;#GlenWSmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer, o:GoldCustomer;
+   foaf:name "Glen W. Smith".
+
+&lt;#AlfredESmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer, o:BronzeCustomer;
+   foaf:name "Alfred E. Smith".
+</pre>
+
+	<p>
+		As long as the resource being retrieved is small enough that the server can form its
+		representation without running into implementation limits on memory etc., and as long
+		as the client is likewise able to consume these representations, this pattern works
+		fine.  Indeed, it's by far the most common pattern on the Web.
+	</p>
+	<p>
+		At the point where server and/or client constraints or consumption preferences come into play, however, 
+		something else is needed.  LDP Paging addresses this need by giving clients and 
+		servers the ability to partition representations into smaller pieces, transfer
+		as many as the client needs (potentially a small subset of the resource's full
+		state), and allows the client to reassemble the pieces (or not) as it prefers.
+		One sees this pattern in contexts such as search page results, as one common
+		example.
+	</p>
+
+</section>
+
+<section id="ldpp-ex-paging-303">
+<h2>Simple paging flow using redirects</h2>
+
+	<p>
+		The simplest possible solution would be to redefine the meaning of the existing
+		URI <code>http://example.org/customer-relations</code> from "all customer relations information"
+		to "the first chunk of all customer relations information".  This would require changes to
+		any existing clients whose code was built using the original definition however, so it's 
+		more likely that Example Co. would mint a new URI for "the first chunk", define a way to 
+		find subsequent chunks, and have clients use this new protocol.
+	</p>
+	<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
+		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
+		LDP Paging does.
+	</p>
+	<p>
+		A client aware of LDP paging obtains a representation of the
+		resource in the usual way, and also signals its ability to handle redirection to a first-page resource:
+	</p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+</pre>
+
+	<p>
+		The server responds with <code>303 See Other</code>, and
+		a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
+		identifying the target resource.  
+	</p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-303-resp1">
+HTTP/1.1 303 See Other
+Location: &lt;http://example.org/customer-relations?page1&gt;
+Transfer-Encoding: chunked
+</pre>
+
+	<p>
+		At this point the client does not know if the target
+		resource is "all" or "the first chunk"; it has to retrieve the resource to know.
+	</p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations?page1 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+</pre>
+	<p>
+		The server responds with status code <code>200 OK</code>, 
+		and the following representation:
+	</p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-303-resp2">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "_87e52ce291112"
+Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
+      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
+Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'
+Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
+
+&lt;&gt;
+   a o:CustomerRelations;
+   dcterms:title "The customer information for Example Co.";
+   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;. 
+
+&lt;#JohnZSmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer;
+   foaf:name "John Z. Smith".
+&lt;#BettyASmith&gt;
+   a foaf:Person;
+   o:status o:PreviousCustomer;
+   foaf:name "Betty A. Smith".
+ &lt;#JoanRSmith&gt;
+   a foaf:Person;
+   o:status o:PotentialCustomer;
+   foaf:name "Joan R. Smith".
+</pre>
+
+	<p>
+		From this response, the client knows that more data exists and where to find it.
+		The server determines the size of the pages using application-specific methods not defined
+		within this specification, with the client's <code>page-size</code> preference as one
+		input; the simplest method is to make the server's page size equal
+		to the client's preference.  In this example, the server chooses a smaller value so 
+		there is a second page.
+	</p>
+	<ul>
+	<li>
+		The <code>Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'</code>
+		response header tells the client which resource <code>&lt;http://example.org/customer-relations?page1&gt;</code>
+		is a page of.  The <code>etag="customer-relations-v1"</code> parameter value gives the client a way to know,
+		during its page traversal, whether or not the canonical <a>paged resource</a> has changed; not all
+		clients will use this information, but it is there for those that can make use of it.
+	</li>
+	<li>
+		The <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code>
+		response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+		needs to examine the other response headers to see if more data existed in the 
+		canonical <a>paged resource</a> when the response
+		was generated by the server.
+	</li>
+	<li>
+		The <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
+		response header tells the client that at least one more <a>in-sequence page resource</a> exists,
+		and how to retrieve its representation.  The next page link's target URI is 
+		defined by the server and is not constrained by this specification.
+	</li>
+	</ul>
+	<p>
+		The following example shows the message exchange for retrieving
+		the next page:
+	</p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations?p=2 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+</pre>
+	<p>
+		The server responds with status code <code>200 OK</code> and the following representation: 
+	</p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-303-resp3">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "8_7e52ce291112"
+Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
+      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
+Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
+
+&lt;&gt;
+   o:client &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 
+ 
+&lt;#GlenWSmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer, o:GoldCustomer;
+   foaf:name "Glen W. Smith".
+
+&lt;#AlfredESmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer, o:BronzeCustomer;
+   foaf:name "Alfred E. Smith".
+ </pre>
+
+	<p>
+		In this example, there are only two customers provided in the
+		second page.  
+	</p>
+		<!-- TODO: show it both ways; if a competing change hit the container, or not -->
+	<ul>
+	<li>
+		The <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code>
+		response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+		needs to examine the other response headers to see if more data existed in the 
+		canonical <a>paged resource</a> when the response
+		was generated by the server.
+	</li>
+	<li>
+		The absence of a <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
+		response header tells the client that no more <a>in-sequence page resource</a>s existed in this <a>paged resource</a>
+		at the time the response was generated; repeating the request might result in a representation with links to more pages,
+		if other processes are updating the customer relations data.
+	</li>
+	<li>
+		Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
+		did not change across the client's process of retrieving the entire page sequence, it is assured that 
+		the merged response representations are equivalent to what it would have received had the server
+		provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
+		The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
+		since the final page's representation was generated.  For example, after the server constructs the final page representation, another
+		actor could delete <code>client#BettyASmith</code> from the server.
+	</li>
+	</ul>
+
+</section>
+
+<section id="ldpp-ex-paging-2nn">
+<h2>Optimized paging flow</h2>
+
+	<p>
+		It is inconvenient that the <a href="#ldpp-ex-paging-303"><code>303 See Other</code> approach</a>
+		requires three message exchanges to transfer two representations.  Fortunately, it is possible to
+		remove the extra message exchange, saving the latency and the server plus network overhead of 
+		servicing the <code>303</code> messages.
+	</p>
+	<p>
+		If a client signals that it is capable of understanding the HTTP
+		<a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>, then the server can
+		respond with <code>2NN Contents of Related</code> instead of <code>303 See Other</code> on the
+		initial retrieval request, and it can also enclose the representation of the first page in the
+		corresponding response.
+	</p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+Prefer: contents-of-related
+</pre>
+
+	<p>
+		The server responds with <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>, 
+		and the representation given below along with its associated response and representation metadata headers.
+	</p>
+	<p>
+		As was true in the <a href="#ldpp-ex-paging-303"></a><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.
+	</p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-2nn-resp1">
+HTTP/1.1 2NN Contents of Related
+Content-Type: text/turtle
+ETag: "_87e52ce291112"
+Location: &lt;http://example.org/customer-relations?page1&gt;
+Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
+      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
+Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'
+Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
+
+&lt;&gt;
+   a o:CustomerRelations;
+   dcterms:title "The customer information for Example Co.";
+   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;. 
+
+&lt;#JohnZSmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer;
+   foaf:name "John Z. Smith".
+&lt;#BettyASmith&gt;
+   a foaf:Person;
+   o:status o:PreviousCustomer;
+   foaf:name "Betty A. Smith".
+ &lt;#JoanRSmith&gt;
+   a foaf:Person;
+   o:status o:PotentialCustomer;
+   foaf:name "Joan R. Smith".
+</pre>
+
+	<p>
+		From this response, the client knows that it received the representation of an
+		<a>in-sequence page resource</a> instead of the <a>paged resource</a>, 
+		that at least one more page exists, and where to find the next page.
+		The server determines the size of the pages using application-specific methods not defined
+		within this specification, with the client's <code>page-size</code> preference as one
+		input; the simplest method is to make the server's page size equal
+		to the client's preference.  In this example, the server chooses a smaller value so 
+		there is a second page.
+	</p>
+	<ul>
+	<li>
+		The <code>2NN Contents of Related</code> status code
+		tells the client that the response contains a representation of some resource <em>other than</em>
+		the one identified by its effective request URI.
+	</li>
+	<li>
+		The <code>Location: &lt;http://example.org/customer-relations?page1&gt;</code>
+		response header tells the client the identifier of the response representation's resource.
+		In the context of a response with a <code>2NN Contents of Related</code> status code,
+		it tells the client the "related" resource's identifier.
+	</li>
+	<li>
+		The <code>Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'</code>
+		response header tells the client which resource <code>&lt;http://example.org/customer-relations?page1&gt;</code>
+		is a page of, providing more specificity about the nature of the relationship between the 
+		resource identified by the effective
+		request URI and the resource identified in the <code>Location</code> header.
+		The <code>etag="customer-relations-v1"</code> parameter value gives the client a way to know,
+		during its page traversal, whether or not the canonical <a>paged resource</a> has changed; not all
+		clients will use this information, but it is there for those that can make use of it.
+	</li>
+	<li>
+		The <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code>
+		response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+		needs to examine the other response headers to see if more data existed in the 
+		canonical <a>paged resource</a> when the response
+		was generated by the server.
+	</li>
+	<li>
+		The <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
+		response header tells the client that at least one more <a>in-sequence page resource</a> exists,
+		and how to retrieve its representation.  The next page link's target URI is 
+		defined by the server and is not constrained by this specification.
+	</li>
+	</ul>
+	<p>
+		The following example shows the message exchange for retrieving
+		the next page:
+	</p>
+
+<em>Request</em>
+<pre class="example">GET /customer-relations?p=2 HTTP/1.1
+Host: example.org
+Accept: text/turtle
+Prefer: return=representation; page-size="500 rdf-triples"
+Prefer: contents-of-related
+</pre>
+	<p>
+		The server responds with status code <code>200 OK</code> and the following representation: 
+	</p>
+
+<em>Response:</em>
+<pre class="example" id="ldpp-ex-paging-2nn-resp2">
+HTTP/1.1 200 OK
+Content-Type: text/turtle
+ETag: "8_7e52ce291112"
+Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
+      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
+Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"
+Allow: GET,OPTIONS,HEAD
+Transfer-Encoding: chunked
+
+#
+#  There is no "next" Link in the server's response, so this is the final page.
+#
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
+
+&lt;&gt;
+   o:client &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 
+ 
+&lt;#GlenWSmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer, o:GoldCustomer;
+   foaf:name "Glen W. Smith".
+
+&lt;#AlfredESmith&gt;
+   a foaf:Person;
+   o:status o:ActiveCustomer, o:BronzeCustomer;
+   foaf:name "Alfred E. Smith".
+ </pre>
+ 
+ 	<p>
+		In this example, there are only two customers provided in the
+		second page.  
+	</p>
+	<ul>
+	<li>
+		The <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code>
+		response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
+		needs to examine the other response headers to see if more data existed in the 
+		canonical <a>paged resource</a> when the response
+		was generated by the server.
+	</li>
+	<li>
+		The absence of a <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
+		response header tells the client that no more <a>in-sequence page resource</a>s existed in this <a>paged resource</a>
+		at the time the response was generated; repeating the request might result in a representation with links to more pages,
+		if other processes are updating the customer relations data.
+	</li>
+	<li>
+		Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
+		did not change across the client's process of retrieving the entire page sequence, it is assured that 
+		the merged response representations are equivalent to what it would have received had the server
+		provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
+		The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
+		since the final page's representation was generated.  For example, after the server constructs the final page representation, another
+		actor could delete <code>client#BettyASmith</code> from the server.
+	</li>
+	</ul>
+
+</section>
+
+</section> <!-- Example message exchanges -->
+
 <section id="ldppclient">
 <h1>Linked Data Platform Paging Clients</h1>
 <p>All of the following are conformance rules for <a title="LDP Paging client">LDP Paging Clients</a>.
 </p>
 <section><h2>General</h2>
 
+	<section id="ldpp-client-advertise"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
+		<a href="#prefer-rules">advertise their ability to support LDP Paging</a> on all retrieval requests that normally result in
+		a response containing a representation.
+	</h2>
+	<div class="ldp-issue-pending" id="what-the-pagesize-required"><p class="ldp-issue-title">For Discussion</p>
+		<p>
+			Given that servers Must Not initiate paging unless the client acks that it understands LDP paging,
+			e.g. by sending a Prefer: pagesize header, do we want to add a Must on clients to send that header?
+			Some support for doing so on the mailing list week of 7 July 2014 resulted in <a href="#ldpp-client-advertise" class="sectionRef">this strawman</a>.
+		</p>
+	</div>
+	</section>
+		
 	<section id="ldpp-client-traversal"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
 		be capable of at least one of <a>forward traversal</a> and/or <a>backward traversal</a>.
 	</h2>
@@ -533,7 +1059,8 @@
 <section id="ldpp-hints-summary">
 <h3>Summary</h3>
 
-	<p>This specification introduces new ...
+	<p>
+		This specification introduces new ...
 	<!-- TODO: fill in summary -->
 	<!-- 
 	parameters on the HTTP <code>Prefer</code> request header's
@@ -559,8 +1086,8 @@
 	<code>Preference-Applied</code> response header when the client cannot otherwise determine the server's
 	behavior with respect to honoring hints from the response content.
 	<a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
+	-->
 	</p>
-	-->
 
 </section> <!-- Prefer summary -->
 
@@ -568,7 +1095,11 @@
 <h3>Specification</h3>
 
 	<section id="ldpp-hints-page-size"><h2 class="normal">
-		The <code>page-size</code> hint defines the client's maximum desired size for a response representation.
+		The <code>page-size</code> hint 
+		<ul>
+		<li>signals the client's support for LDP Paging to the request server</li>
+		<li>defines the client's maximum desired size for a response representation</li>
+		</ul>
 		A client communicates its hint to the server by adding a 
 		HTTP preference request header with
 		<code>return=representation</code> that includes a
@@ -591,7 +1122,8 @@
 		preference parameter; LDP Paging assigns a meaning to the value only when it is a quoted string.
 		<a title="LDP Paging server">LDP Paging servers</a> MAY 
 		ignore a page size of zero, or unrecognized <code>units</code>, 
-		and process the request as if the hint was absent.
+		and process the request as if no maximum desired size was specified; in the latter case the server
+		can select whatever page size it deems appropriate.
 		</p>
 		</blockquote>
 	</section>
@@ -620,6 +1152,13 @@
 
 <section class="informative" id="ldpr-informative">
 <h2>Introduction</h2>
+	<div class="ldp-issue-closed"><p class="ldp-issue-title">Editorial note</p>
+		<p>
+			There is more duplication between this content (its original home) and other sections
+			(<a href="#intro" class="sectionRef"></a>, <a href="#ldpp-ex-mx" class="sectionRef"></a>) than we'd prefer.
+			It's on-going work to reduce the duplication.
+		</p>
+	</div>
 	<p>
 		Some LDPRs are too large to reasonably transmit a representation in a
 		single HTTP response.  
@@ -665,6 +1204,13 @@
 <section class="informative" id="ldpr-PagingIntro">
 
 <h3>Introduction</h3>
+	<div class="ldp-issue-closed"><p class="ldp-issue-title">Editorial note</p>
+		<p>
+			There is more duplication between this content (its original home) and other sections
+			(<a href="#intro" class="sectionRef"></a>, <a href="#ldpp-ex-mx" class="sectionRef"></a>) than we'd prefer.
+			It's on-going work to reduce the duplication.
+		</p>
+	</div>
 	<p>
 		<a title="LDP Paging server">LDP Paging servers</a> may respond to requests for a
 		resource by redirecting to the first page of the resource and, with that, returning 
@@ -684,132 +1230,7 @@
 		retrieve all the <a>in-sequence page resource</a>s without the <a>paged resource</a>
 		being added to or changed, so clients requiring such a guarantee 
 		may not find all <a>paged resource</a>s usable in practice.
-	</p>
-	<p>
-		Looking at an example resource representing Example Co.'s customer
-		relationship data, identified by the URI <code>http://example.org/customer-relations</code>,
-		we’ll split the response across two pages.  
-	</p>
-
-<em>Request</em>
-<pre class="example">GET /customer-relations HTTP/1.1
-Host: example.org
-Accept: text/turtle
-</pre>
-	<p>
-		The server responds with <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>, 
-		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,
-		and the following representation:
-	</p>
-
-<em>Response:</em>
-<pre class="example" id="ldpc-ex-page1">
-HTTP/1.1 2NN Contents of Related
-Content-Type: text/turtle
-ETag: "_87e52ce291112"
-Location: &lt;http://example.org/customer-relations?page1&gt;
-Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
-      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
-Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'
-Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"
-Allow: GET,OPTIONS,HEAD
-Transfer-Encoding: chunked
-
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
-
-&lt;&gt;
-   a o:CustomerRelations;
-   dcterms:title "The customer information for Example Co.";
-   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;. 
-
-&lt;#JohnZSmith&gt;
-   a foaf:Person;
-   o:status o:ActiveCustomer;
-   foaf:name "John Z. Smith".
-&lt;#BettyASmith&gt;
-   a foaf:Person;
-   o:status o:PreviousCustomer;
-   foaf:name "Betty A. Smith".
- &lt;#JoanRSmith&gt;
-   a foaf:Person;
-   o:status o:PotentialCustomer;
-   foaf:name "Joan R. Smith".</pre>
-
-	<p>
-		Because the server includes a <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
-		response header, and the status code is 2xx (<code>2NN Contents of Related</code> in this case), 
-		the client knows that more data exists and where to find it.
-		The server determines the size of the pages using application specific methods not defined
-		within this specificiation. The next page link's target URI is also
-		defined by the server and not this specification.
-	</p>
-	<p>
-		The following example is the result of retrieving
-		the next page:
-	</p>
-
-<em>Request</em>
-<pre class="example">GET /customer-relations?p=2 HTTP/1.1
-Host: example.org
-Accept: text/turtle
-</pre>
-	<p>
-		The server responds with status code <code>200 OK</code> and the following representation: 
-	</p>
-
-<em>Response:</em>
-<pre class="example" id="ldpc-ex-page2">
-HTTP/1.1 200 OK
-Content-Type: text/turtle
-ETag: "8_7e52ce291112"
-Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
-      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
-Link: &lt;http://example.org/customer-relations&gt;; rel='canonical'; etag="customer-relations-v1"
-Allow: GET,OPTIONS,HEAD
-Transfer-Encoding: chunked
-
-#
-#  There is no "next" Link in the server's response, so this is the final page.
-#
[email protected] rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
[email protected] dcterms: &lt;http://purl.org/dc/terms/&gt;.
[email protected] foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
[email protected] ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
[email protected] o: &lt;http://example.org/ontology/&gt;.
[email protected] &lt;http://example.org/customer-relations&gt;.
-
-&lt;&gt;
-   o:client &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 
- 
-&lt;#GlenWSmith&gt;
-   a foaf:Person;
-   o:status o:ActiveCustomer, o:GoldCustomer;
-   foaf:name "Glen W. Smith".
-
-&lt;#AlfredESmith&gt;
-   a foaf:Person;
-   o:status o:ActiveCustomer, o:BronzeCustomer;
-   foaf:name "Alfred E. Smith".
- </pre>
-	<p>
-		In this example, there are only two customers provided in the
-		second page.  To indicate this is also the last page, the server omits the <code>Link: rel='next'</code> 
-		header in its response.  The client combines the representations as appropriate for the media type;
-		in this case, an RDF graph merge is the logical choice.
-	</p>
-		<!-- TODO: show it both ways; if a competing change hit the container, or not -->
-	<p>
-		As mentioned above, retrieving all the pages offered by a server gives no guarantee to a client
-		that it knows the entire state of the <a>paged resource</a> on the server, unless the client also
-		verifies that the <a>paged resource</a> has not changed.  For example, after the server constructs the
-		the first page representation, another
-		actor could delete <code>client#BettyASmith</code> from the server.  
+		A detailed example is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
 	</p>
 </section>
 <section class="informative" id="ldpr-impl">
@@ -824,9 +1245,10 @@
 		its next page links, for example.
 	</p>
 	<p>
-		Observe that in the preceding example, it is likely that the <var>page n</var> URIs are all of the form
+		Observe that in the <a href="#ldpp-ex-mx" class="sectionRef">preceding examples</a>, 
+		the <var>page n</var> URIs are all of the form
 		<code>http://example.org/customer-relations?p=<var>n</var></code>, 
-		where <var>n</var> is <var>2..n</var>.
+		where <var>n</var> is <var>2..n</var>.  This is likely true in general practice.
 		If the server allocates <code>o:client</code> representations to pages randomly, it's not obvious how to avoid
 		keeping per-client state of one kind or another on the server while still sending all the representations on
 		at least one page.  In the common case where the list has an 
@@ -1238,7 +1660,9 @@
 		discover <dfn><abbr title="Linked Data Platform Containers">LDPCs</abbr></dfn>.</p>
 
 	<div class="ldp-issue-pending" id="what-the-new-container"><p class="ldp-issue-title">For Discussion</p>
-		<p>Are we attempting to define a new type of container here?  If not, should delete the clause.</p>
+		<p>Are we attempting to define a new type of container here?  If not, should delete the clause.
+			Some support for doing so on the mailing list week of 7 July 2014.
+		</p>
 	</div>
 		
 	<section id="ldpc-isldpr"><h2 class="normal">Each Linked Data Platform Paging Container MUST also be 
@@ -1248,7 +1672,7 @@
 	<section id="ldpc-onsamepage"><h2 class="normal">
 		<a title="LDP Paging server">LDP Paging servers</a> MUST
 		ensure that the <a title="membership triples">membership triple</a> and 
-		<a title="containment triples">containment triple</a> for each member are on the
+		<a title="containment triples">containment triple</a> for each member are part of the
 		same <a>in-sequence page resource</a>, whenever both triples are present in the page sequence
 		for a <a title="paged resource">paged LDPC</a>.
 	</h2></section>
@@ -1452,7 +1876,7 @@
 </section>
 
 
-<section class='appendix informative'>
+<section class='appendix informative' id="acks">
 <h2>Acknowledgements</h2>
      
   <p>The following people have been instrumental in providing thoughts, feedback,
@@ -1474,6 +1898,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 - Move paging example into "intro" chapter 4 (JA) </li>
 	<li>2014-07-08 - Resolve a set of editorial to-dos (JA) </li>
 	<li>2014-07-07 - Clients must consent to/invite paging per 20140630 resolution 2 (JA) </li>
 	<li>2014-07-07 - Rename single-page resource to in-sequence page resource per 20140630 resolution 3 (JA) </li>