feat: separated semantic of cursor and implementation details (#445)

chapters/naming.adoc

@@ -148,20 +148,22 @@ deliver the same results whether they have the trailing slash or not.
 If you provide query support for searching, sorting, filtering, and
 paginating, you must stick to the following naming conventions:
 
-* `q` — default query parameter (e.g. used by browser tab completion);
-  should have an entity specific alias, like sku
-* `sort` — comma-separated list of fields to define the sort order. To
-  indicate sorting direction, fields may be prefixed with + (ascending) or
-  - (descending), e.g. /sales-orders?sort=+id
+* `q` — default query parameter (e.g. used by browser tab completion); should
+  have an entity specific alias, like sku
+* `sort` — comma-separated list of fields to define the sort order. To indicate
+  sorting direction, fields may be prefixed with `+` (ascending) or `-`
+  (descending), e.g. /sales-orders?sort=+id
 * `fields` — to retrieve only a subset of fields of a resource. See <<157>>
   below.
 * `embed` — to expand or embedded sub-entities (ie.: inside of an article
   entity, expand silhouette code into the silhouette object). Implementing
   `embed` correctly is difficult, so do it with care. See <<158>> below.
 * `offset` — numeric offset of the first element on a page. See <<pagination>>
   section below.
-* `cursor` — encoded pointer to the first or last element on a page, the
-  pagination direction, and the applied query filters. See <<pagination>>
-  section below.
+  paque value, never to be inspected/constructed, addresses a single page
+* `cursor` — an opaque pointer to a page, never to be inspected/constructed by
+  clients. It usually (encrypted) encodes the identifier of the first or last
+  page element, the pagination direction, and the applied query filters to
+  recreate the collection. See <<pagination>> section below.
 * `limit` — client suggested limit to restrict the number of entries on
   a page. See <<pagination>> section below.