[Telepathy-commits] [telepathy-spec/master] ContactSearch: improve wording of x-search-offset

[Simon McVittie]

---
 spec/Channel_Type_Contact_Search.xml |   35 +++++++++++++++++++--------------
 1 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 895210b..7858c95 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -205,23 +205,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           </dd>
 
           <dt><code>x-search-offset</code></dt>
-          <dd>For protocols that support paging results, the offset from the
-            start of the results that should be returned. For example, if the
-            search terms match <i>Antonius</i>, <i>Bridget</i> and
-            <i>Charles</i> and this key is set to <code>"2"</code>, the search
-            service SHOULD only return <i>Charles</i>.</dd>
-
-          <dd>Connection managers for protocols which do not natively support
-            restricting the number of results returned MUST NOT support this
-            term (or <code>x-search-limit</code>): all results should be
-            signalled, and the client can provide its own paging as
-            desired.</dd>
+          <dd>
+            <p>For protocols that support paging results, the offset from the
+              start of the results that should be returned, i.e. the number of
+              contacts from the beginning that should be omitted.</p>
+
+            <p>For example, if the search terms match 50 contacts, this key
+              is set to <code>"20"</code> and <code>x-search-limit</code>
+              is set to <code>"10"</code>, then the ten contacts from the 21st
+              to the 30th should be returned.</p>
+
+            <p>Connection managers for protocols which do not natively support
+              restricting the number of results returned MUST NOT support
+              either this term or <code>x-search-limit</code>: all results
+              should be signalled, and the client can provide its own paging as
+              desired.</p>
+          </dd>
 
           <dt><code>x-search-limit</code></dt>
-          <dd>For protocols that support paging results, the maximum number of
-            results that should be returned.  For example, if the search terms
-            match <i>Antonius</i>, <i>Bridget</i> and <i>Charles</i> and this
-            key is set to <code>"2"</code>, the search service SHOULD only
+          <dd>For protocols that support limiting results, the maximum number
+            of results that should be returned.  For example, if the search
+            terms match <i>Antonius</i>, <i>Bridget</i> and <i>Charles</i> and
+            this key is set to <code>"2"</code>, the search service SHOULD only
             return <i>Antonius</i> and <i>Bridget</i>.</dd>
         </dl>
       </tp:docstring>
-- 
1.5.6.5