Draft section describing new link relations

[GoogleCodeExporter]

Please draft a section of specification text that describes the each of the new 
link relations that this 
specification creates.

These should come from [MetadataAndLinkRelations]

Please note that any discussion should happen on the mailing list rather
than the comments of the issue tracker.

Mailing list threads should reference the number of any open Issue in the
Subject line " (#ISSUE)".

Original issue reported on code.google.com by abdela...@gmail.com on 7 Apr 2010 at 4:05

[GoogleCodeExporter]

Original comment by ed.summers on 7 Apr 2010 at 8:26

• Added labels: Milestone-Release1.0

[GoogleCodeExporter]

Original comment by liza31337@gmail.com on 21 Apr 2010 at 2:59

[GoogleCodeExporter]

Ed: Please contribute a rough draft of this section before the 8am Pacific call 
tomorrow, 5 May 2010.

Original comment by abdela...@gmail.com on 4 May 2010 at 6:15

[GoogleCodeExporter]

+== Catalog Relations ==
+
+OPDS Catalog Documents SHOULD include links to other available Publication and 
Hierarchical Collections 
and other related Resources to encourage independent navigation. This 
specification defines six new relations 
for linking from OPDS Catalog Documents at the feed level:
+
+  * "http://opds-spec.org/bookshelf": A Resource that includes a user's 
existing set of electronic 
publications, which MAY be represented as an OPDS Catalog.
+  * "http://opds-spec.org/crawlable": A complete OPDS Catalog in a single, 
unpaged atom:feed. See 
Complete Publication Collections.
+  * "http://opds-spec.org/sort/featured": A Publication Collection with 
featured Entries.
+  * "http://opds-spec.org/sort/new": A Publication Collection with newly 
released Entries.
+  * "http://opds-spec.org/sort/popular": A Publication Collection with popular 
Entries.
+  * "http://opds-spec.org/subscriptions": TODO
+
+The following relations are derived from `[DRAFT-Web-Linking]`, with some 
clarification:
+
+  * "alternate": This Catalog in another format.
+  * "first": The initial page in a paginated Publication Collection.
+  * "help": A Resource that describes how the Catalog or publications may be 
used.
+  * "last": The final page in a paginated Publication Collection.
+  * "next": The following page in a paginated Publication Collection.
+  * "previous": The previous page in a paginated Publication Collection.
+  * "related": A Publication Collection that  (best way to suggest related 
OPDS collection feeds. For example 
while browsing new release in romance, a related link could suggest the most 
popular publications in 
romance)
+  * "self": This Catalog.
+  * "start": The OPDS Catalog Root.
+  * "subsection: A Hierarchical Collection not better described by a more 
specific relation. 
+  * "up": The parent of this Catalog in a Hierarchical Collection.
+

Original comment by abdela...@gmail.com on 4 May 2010 at 11:44

[GoogleCodeExporter]

 == Entry Relations ==
 +OPDS Catalog Documents SHOULD include links to related Resources. This specification defines five new relations for linking from OPDS Catalog Entry Documents. They are defined in the Sections Acquisition Relations and Covers 
and Artwork Relations.

+The following relations are derived from `[DRAFT-Web-Linking]`, with some 
clarification:

+  * "alternate": Identifies a Resource that describes this electronic 
publication in another format (a
+  * "copyright": Refers to a copyright statement that applies to this OPDS 
Catalog Entry.
+  * "latest-version": Refers to a more recent version of the electronic 
publication described by this OPDS Catalog Entry.
+  * "license": Refers to a license associated with this OPDS Catalog Entry.
+  * "related": Refers to a similar OPDS Catalog Entry.
+  * "replies ": Refers to a comment on or discussion of this OPDS Catalog 
Entry.
+
+=== Acquisition Relations ===
+
+Acquisition Relations describe the extent of the content referred to by an 
Acquisition Link or the manner in which that Resource may be acquired. This 
specification defines five Acquisition Relations, which all begin with 
"http://opds-spec.org/acquisition": 
+
+  * "http://opds-spec.org/acquisition": Indicates that the complete 
representation of the content Resource may be retrieved without payment.
+  * "http://opds-spec.org/acquisition/borrow": Indicates that the complete 
representation of the content Resource may be retrieved as part of a lending 
transaction.
+  * "http://opds-spec.org/acquisition/buy": Indicates that the complete 
representation of the content Resource may be retrieved as part of a purchase.
+  * "http://opds-spec.org/acquisition/sample": Indicates that a subset of the 
content Resource may be retrieved.
+  * "http://opds-spec.org/acquisition/subscribe": Indicates that the complete 
representation of the content Resource may be retrieved as part of a 
subscription.
+

Original comment by abdela...@gmail.com on 5 May 2010 at 12:34

[GoogleCodeExporter]

Thanks for doing all this work for me Keith :-)

Original comment by ed.summers on 5 May 2010 at 1:16

[GoogleCodeExporter]

I'm not sure I like the hierarchical URIs: 

 * http://opds-spec.org/acquisition
 * http://opds-spec.org/acquisition/borrow

why not:

 * http://opds-spec.org/acquisition
 * http://opds-spec.org/borrow

the hierarchy implies some sort of realtionship. Also maybe we should use a 
PURL so 
we can move stuff around? It will also make it possible to redirect from a 
bunch of 
URIs to one namespace document. Like what the dublin core people do.

 * http://purl.org/opds/acquisition

Original comment by ed.summers on 5 May 2010 at 3:01

[GoogleCodeExporter]

Well, we do have a relationship: they're all acquisition links and it makes 
sense to 
easily identify them.

Original comment by hadrien....@gmail.com on 5 May 2010 at 3:09

[GoogleCodeExporter]

Specifically, we use the same prefix for the set of related relations because 
of the desired to write this 
sentence:

> Each OPDS Catalog Entry Document MUST include at least one Acquisition Link, 
which is an atom:link 
element with a relation that begins "http://opds-spec.org/acquisition".

and this code
{{{
for acq_link in 
catalog.xpath("/atom:feed/atom:entry/atom:link[starts-with(@rel, 'http://opds-
spec.org/acquisition')]", namespaces=NSS):
  # interesting stuff
}}}

---

Save the discussion above, is there more work that needs to be done on 
describing the new relations?

Original comment by abdela...@gmail.com on 5 May 2010 at 4:52

• Changed state: Started

[GoogleCodeExporter]

Ok, I tend to avoid hierarchy when possible -- it always seems to be hard to 
change 
... but if you both are in agreement that's good enough for me.

Original comment by ed.summers on 11 May 2010 at 11:17

• Changed state: Fixed

[GoogleCodeExporter]

Original comment by abdela...@gmail.com on 25 May 2010 at 5:44

• Added labels: Milestone-Release0.9