search

abdelazer / openpub

Automatically exported from code.google.com/p/openpub
0 stars 0 forks source link

Terminology section (and terminology throughout) #27

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
The draft spec notes that OPDS "refines" the Atom spec, and Keith noted in 
the call today that OPDS catalogs will be valid Atom.

I think that we should use "feed" and "entry" to describe the essential 
structures when speaking generically. A feed is what you're subscribing to; 
an entry describes what the feed lets you acquire (in our case, a 
"publication"; see postscript below).

When differentiation is necessary atom:feed and atom:entry should be used 
to restrict the reference to pre-OPDS or non-OPDS documents.

The chief goal of the specification's descriptive parts ought to be 
enabling someone who already produces (or reads) an Atom feed to quickly 
adapt it to deal with OPDS specifics. (My opinion.)

Right now, we have way too many terms -- feed, entry, catalog, catalog 
document, catalog entry document, collection (and the variants, like OPDS 
catalog entry document) that muddy the water.

Perhaps we should just say "OPDS feed" to mean what we now call a 
publication collection -- one feed with entries that point to a 
publication, including an acquisition link. (Is this also what is meant by 
OPDS catalog entry document? The differentiation between them is cloudy.)

And an "OPDS catalog" would then simply be what's being called a 
hierarchical collection, eg, a feed that only has links to individual OPDS 
feeds with those publication entries. (Also 'hierarchical' implies one type 
of organization. What about the circumstance, for instance, of Editions S, 
which has four feeds: fiction, books with red covers, books that include 
color video, and  books found in the J Frank Dobie collection at the 
Humanities Research Center, with the first two comprising books published 
by Editions S and the other two being aggregations from other publishers 
and not sold by Eds. S?)

In this view, an OPDS feed that's part of a larger OPDS catalog might have 
atom:links to its parent and related feeds. But it might not and 
information for cross-feed navigation wouldn't be required of the OPDS 
feed. So, gosh-darn it, a publisher with just one OPDS feed might call it 
an OPDS catalog even though it doesn't have links to anything but 
publications. To me, that's not a problem. OPDS feed and OPDS catalog ought 
to pretty much mean the same thing in people's minds, even though we make a 
distinction between a list of entries and a list of feeds.

If my suggestions are untenable, at least the text ought not to confuse 
people as to which parts of our spec are "like an Atom feed" and which 
parts "like an Atom entry."

Roger Sperberg

PS: I don't really understand why using this 'refinement' of Atom -- 
specifically extending it to require acquisition links -- restricts itself 
to use for electronic texts, aka publications. 

For one thing, any electronic content could be processed this way. For 
another, "acquisition" could also mean reserving a physical print book at 
my town library or having it shipped to my street address. Other than the 
means and timing of the delivery, how are these different? It seems to me 
that the crucial distinction is in the catalog being electronic and 
occurring in real-time (instead of on paper and mailed) and not necessarily 
the end product.

Original issue reported on code.google.com by rsperb...@gmail.com on 5 May 2010 at 8:02

GoogleCodeExporter commented 9 years ago 
From my perspective, the advantage of Catalog nomenclature is that it is well
understood by target publishing audiences, whereas technical ATOM based 
terminology
is opaque to most.  In presentations, I have personally not made a distinction
between a Catalog as a compilation of direct resource links vs a (meta-) 
aggregation
of other compilations of resource links, and I think there may not necessarily 
be
utility to one, at least in the kind of casual marketing/ business development
conversations that I tend to engage in.

Original comment by naypi...@gmail.com on 5 May 2010 at 8:52

GoogleCodeExporter commented 9 years ago 
I agree that we could make things slightly easier to understand.

Maybe we should avoid some terms like "Hierarchy" and "Publication" when we 
describe 
a feed.

Essentially, we have two different refinements: feeds that are used for 
navigation 
and feeds that are used for acquisition. A feed can't be both at the same time.

Roger is right when he says that a "Publication Feed" could contain anything. 
Cart 
even has an example of such a feed where they distribute audiobooks rather than 
ebooks.
Therefore, maybe we should rename it to "Acquisition Feed" (a feed where you 
can 
acquire content) or something similar, while the other type of feed could be a 
"Navigation Feed" (a feed where you can access other feeds).

A Catalog for me means something different: it's the aggregation of all feeds 
and 
entries for a single source of content.

Original comment by hadrien....@gmail.com on 6 May 2010 at 10:29

GoogleCodeExporter commented 9 years ago 
Hadrien's suggestions make sense to me.

"Navigation" more accurately describes a feed from which you access other feeds 
than 
"hierarchical collection."

"Acquisition" succinctly underscores what this feed does that Atom-plain 
doesn't.

On first consideration, "Content" (eg, content feed) appealed to me with its 
universal application, but an atom:entry links to a (full) blog post, and just 
as 
some people are blogging books (like Pepys' Diary) there's really no reason a 
plain 
Atom feed couldn't serve complete books, section by section. So content feed 
has a 
tinge of ambiguity we probably should avoid. "Content acquisition" is clear but 
carries no information that "acquisition" alone doesn't as well.

I've often approached the OPDS effort as a natural use of Atom, with our steady 
flow 
of new titles needing to be brought to readers' attention. In that guise, OPDS  
answers the question of "How do we represent our spring catalog 
electronically?" 

Peter's statement, however, reminds me that a library catalog doesn't represent 
just 
new releases and re-releases, a publisher's frontlist, but the entire 
collection.

And if entries do indeed have the metadata needed to find a particular book or 
set of 
books — as well as that ever-significant acquisition link — then "catalog" 
is a more 
meaningful label than "feed" with its roots in the need to 
stay-current-with-ever-
changing-blogs and keep-up-with-things-changing-in-internet-time.

Like Peter, I'm not sure the distinction between navigation uses and 
acquisition uses 
matters in general discourse. So I'm happy enough with "OPDS catalog" as a 
description of what our spec describes. I just want it clear that when we say 
"pouring our type of content into an Atom feed makes it act like this," people 
implementing the OPDS spec see how to use what they know about Atom; and when 
we say 
"this is something we need that blogs don't," they know why we're using terms 
that 
don't appear in [RFC4287].

Roger

Original comment by rsperb...@gmail.com on 6 May 2010 at 2:06

GoogleCodeExporter commented 9 years ago

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

GoogleCodeExporter commented 9 years ago 
I've consolidated the vocab in this draft: 
http://code.google.com/p/openpub/source/diff?
spec=svn227&r=227&format=side&path=/wiki/CatalogSpecDraft.wiki

Original comment by abdela...@gmail.com on 12 May 2010 at 7:18

GoogleCodeExporter commented 9 years ago

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