--- a/ldp-paging.html Tue Jul 08 09:09:59 2014 -0500
+++ b/ldp-paging.html Tue Jul 08 11:36:15 2014 -0400
@@ -4,7 +4,7 @@
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-15#resolution_7 : At a minimum, on paging, we'll provide a way for clients to detect that a triple fell through the cracks during paging.
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 3: spec sandro's paging proposal
DONE: http://www.w3.org/2012/ldp/track/issues/94 -> http://www.w3.org/2013/meeting/ldp/2014-05-12#resolution_3 2014-04-17 resolution 3: spec sandro's paging proposal
- STARTED: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
+ TODO: STARTED: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 5: contains+member triple always on same page
DONE: http://www.w3.org/2013/meeting/ldp/2014-05-12 resolution 4: ordering undefined when paging non-LDPC LDPRs
@@ -267,7 +267,7 @@
<!-- TODO: Move bulk of paging intro here - it's not rocket science -->
<h1>Introduction</h1>
<p>This specification provides a widely re-usable pattern to deal with large resources.
- Depending on the server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
+ Depending on the client's and server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
be redirected to a <a title="In-Sequence Page resource">subset of the resource (one page)</a>, that provides access to subsequent pages
(see <a href="#ldpr-Paging" class="sectionRef"></a>).
</p>
@@ -279,7 +279,7 @@
<h1>Terminology</h1>
<section id="terms-from-ldp">
-<h2>Terms re-used from the Linked Data Platform.</h2>
+<h2>Terms re-used from the Linked Data Platform</h2>
<p>This section is non-normative. It summarizes a subset of terms formally defined in [[LDP]] for the reader's convenience.
</p>
@@ -353,7 +353,7 @@
<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>,
each of which contains a subset of the state
- of another resource <var>P</var>. <var>P</var> is called the paged resource.
+ of another resource <var>P</var>, called the <a>paged resource</a>.
For readers
familiar with paged feeds [[RFC5005]], an in-sequence page resource is similar to a feed document and the same
coherency/completeness considerations apply.
@@ -446,11 +446,17 @@
<p><em>TODO</em>: Update this section list</p>
<ul>
<li>1. Introduction: <b>non-normative</b></li>
- <li>2. Terminology: <b>normative</b></li>
+ <li>2. Terminology</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>
+ </ul>
<li>3. Conformance: <b>normative</b></li>
- <li>4. Linked Data Platform Resources: <b>normative</b></li>
- <li>5. Linked Data Platform Containers: <b>normative</b></li>
- <li>6. HTTP Header Definitions: <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>
@@ -501,6 +507,96 @@
</section>
</section>
+
+<section id="ldpp-hints">
+<h2>Client hints</h2>
+ <p>
+ Clients can provide paging-related hints to influence the server's choices.
+ </p>
+
+<section id="ldpp-hints-summary">
+<h3>Summary</h3>
+
+ <p>This specification introduces new ...
+ <!-- TODO: fill in summary -->
+ <!--
+ parameters on the HTTP <code>Prefer</code> request header's
+ <code>return=representation</code> preference [[!RFC7240]], used optionally by clients to
+ supply a hint to help the server form a response that is most appropriate to
+ the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
+ client application is interested in and, if received, is likely to be
+ processed. LDP Containers with large numbers of associated documents
+ and/or members will have large representations, and many client
+ applications may be interested in processing only a subset of the LDPC's
+ information (for example, only membership triples or only containment triples),
+ resulting in a potentially large savings in server, client,
+ and network processing.
+ </p>
+
+ <p>
+ Non-normative note: LDP server implementers should carefully consider the effects of these
+ preferences on caching, as described in section 2 of [[!RFC7240]].
+ </p>
+
+ <p>
+ Non-normative note: [[!RFC7240]] recommends that server implementers include a
+ <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 -->
+
+<section id="prefer-rules">
+<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.
+ A client communicates its hint to the server by adding a
+ HTTP preference request header with
+ <code>return=representation</code> that includes a
+ <code>page-size</code> parameter whose value adheres to the following syntax:
+ </h2>
+ <pre><code>
+ page-size-parameter = "page-size" *WSP "=" *WSP DQUOTE *WSP 1*DIGIT 1*WSP 1*units *WSP DQUOTE
+ units = rdf-triples / extension-units
+ rdf-triples = "rdf-triples" ; units = RDF triples
+ extension-units = token ; other units allowed for future extensibility
+ </code></pre>
+ <blockquote>
+ <p>
+ Where <code>WSP</code> is whitespace [[!RFC5234]],
+ <code>DIGIT</code> is an integer between zero and nine [[!RFC5234]],
+ <code>DQUOTE</code> is a double quote [[!RFC5234]],
+ and
+ <code>token</code> is as defined in [[!RFC7230]].
+ The generic preference BNF [[!RFC7240]] allows either a quoted string or a token as the value of a
+ 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.
+ </p>
+ </blockquote>
+ </section>
+
+</section> <!-- Prefer specification -->
+
+<section id="prefer-examples" class="informative">
+<h3>Examples</h3>
+
+ <p id="prefer-examples-direct-minimal-container-only1">
+ Clients interested in receiving at most 500 RDF triples per <a title="in-sequence page resource">page</a>
+ would use add this HTTP header on a <code>GET</code> request:
+ <code>Prefer: return=representation; page-size="500 rdf-triples"</code>
+ </p>
+
+
+</section> <!-- Prefer examples -->
+
+
+</section> <!-- Paging hints -->
+
</section> <!-- Client constraints -->
<section id="ldpr">
@@ -965,95 +1061,6 @@
</section> <!-- h2 -->
-<section id="ldpp-hints">
-<h2>Paging-related client hints</h2>
- <p>
- Clients can provide paging-related hints to influence the server's choices.
- </p>
-
-<section id="ldpp-hints-summary">
-<h3>Summary</h3>
-
- <p>This specification introduces new ...
- <!-- TODO: fill in summary -->
- <!--
- parameters on the HTTP <code>Prefer</code> request header's
- <code>return=representation</code> preference [[!RFC7240]], used optionally by clients to
- supply a hint to help the server form a response that is most appropriate to
- the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
- client application is interested in and, if received, is likely to be
- processed. LDP Containers with large numbers of associated documents
- and/or members will have large representations, and many client
- applications may be interested in processing only a subset of the LDPC's
- information (for example, only membership triples or only containment triples),
- resulting in a potentially large savings in server, client,
- and network processing.
- </p>
-
- <p>
- Non-normative note: LDP server implementers should carefully consider the effects of these
- preferences on caching, as described in section 2 of [[!RFC7240]].
- </p>
-
- <p>
- Non-normative note: [[!RFC7240]] recommends that server implementers include a
- <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 -->
-
-<section id="prefer-rules">
-<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.
- A client communicates its hint to the server by adding a
- HTTP preference request header with
- <code>return=representation</code> that includes a
- <code>page-size</code> parameter whose value adheres to the following syntax:
- </h2>
- <pre><code>
- page-size-parameter = "page-size" *WSP "=" *WSP DQUOTE *WSP 1*DIGIT 1*WSP 1*units *WSP DQUOTE
- units = rdf-triples / extension-units
- rdf-triples = "rdf-triples" ; units = RDF triples
- extension-units = token ; other units allowed for future extensibility
- </code></pre>
- <blockquote>
- <p>
- Where <code>WSP</code> is whitespace [[!RFC5234]],
- <code>DIGIT</code> is an integer between zero and nine [[!RFC5234]],
- <code>DQUOTE</code> is a double quote [[!RFC5234]],
- and
- <code>token</code> is as defined in [[!RFC7230]].
- The generic preference BNF [[!RFC7240]] allows either a quoted string or a token as the value of a
- 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.
- </p>
- </blockquote>
- </section>
-
-</section> <!-- Prefer specification -->
-
-<section id="prefer-examples" class="informative">
-<h3>Examples</h3>
-
- <p id="prefer-examples-direct-minimal-container-only1">
- Clients interested in receiving at most 500 RDF triples per <a title="in-sequence page resource">page</a>
- would use add this HTTP header on a <code>GET</code> request:
- <code>Prefer: return=representation; page-size="500 rdf-triples"</code>
- </p>
-
-
-</section> <!-- Prefer examples -->
-
-
-</section> <!-- Paging hints -->
-
</section> <!-- h1 -->
@@ -1297,11 +1304,6 @@
</section> <!-- Base specs -->
<section>
-<h1>HTTP Header Definitions</h1>
-
-<p><em>TBD</em></p>
-
-</section> <!-- Header defns -->
<!-- Removed for action-113
<section>