search

abdelazer / openpub

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

Clarify usage of atom:summary and atom:content #29

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
Please make mention of the atom:summary tag and clarify when to use
atom:summary vs. atom:content. Clarify the semantics of each and state that
reading systems should use one or the other, but not both.

Perhaps make a statement that text content is preferred over html or xhtml
content. By the way, links in html/xhtml content may be problematic in some
reading systems that are not rendering the page in a browser.

Also, an example would be very helpful to make the usage clear.

Original issue reported on code.google.com by patrick....@gmail.com on 12 May 2010 at 4:36

GoogleCodeExporter commented 9 years ago

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

GoogleCodeExporter commented 9 years ago 
This is what I ended up with. Please let me know how to improve it.

I intentionally left out any mention of content types, as I think we should 
just defer transparently to Atom on 
this issue.

+== Summary and Content ==
+ 
+OPDS Catalog Entries MAY include either "atom:summary" or "atom:content" 
elements or both to provide a 
description, summary, abstract, or excerpt of the Publication. The content of 
an "atom:summary" element 
MUST be text and SHOULD NOT duplicate the content of "atom:title" or 
"atom:content".
+
+If an OPDS Catalog Entry includes both "atom:content" and "atom:summary", the 
"atom:content" SHOULD NOT 
be included in the Partial Catalog Entry. Both elements SHOULD be included in 
the Complete Catalog Entry.

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

GoogleCodeExporter commented 9 years ago 
It's pretty clear overall but I'm afraid that using "MAY" in the first 
paragraph could 
negatively impact the perception of the reader about such requirements.

In Atom it is required to have an atom:content, an atom:summary or an 
atom:link@rel="alternate". Since we certainly don't want to enforce the 
requirement of 
a full entry, it means that a partial entry MUST have either an atom:content or 
atom:summary.

Original comment by hadrien....@gmail.com on 21 May 2010 at 3:51

GoogleCodeExporter commented 9 years ago 
You're right. 

+ OPDS Catalog Entries SHOULD include either "atom:summary" or "atom:content" 
elements

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

GoogleCodeExporter commented 9 years ago

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

GoogleCodeExporter commented 9 years ago 
Reopening this following feedback from Dave Thomas. We need to be more clear on 
what constraints are imposed on top of Atom's and what is reasonable.

Original comment by abdela...@gmail.com on 18 Aug 2010 at 4:39

GoogleCodeExporter commented 9 years ago 
http://code.google.com/p/openpub/wiki/CatalogSpecDraft#Summary_and_Content

Here's the new text; feedback welcome.

"""
OPDS Catalog Entries use "atom:content" and "atom:summary" elements to describe 
a Publication. This is a distinction from Atom [RFC4287], which uses 
"atom:content" for the "content of the entry." Instead, OPDS Catalog Entries 
reference an electronic document with the Publication's content using 
Acquisition Links. OPDS Catalog Entries SHOULD include either "atom:summary" or 
"atom:content" elements or both to provide a description, summary, abstract, or 
excerpt of the Publication.

An "atom:summary" element in an OPDS Catalog Entry MUST use a "type" attribute 
of "text" and the content MUST NOT contain child elements. The content of an 
"atom:summary" element SHOULD NOT duplicate the content of "atom:title" or 
"atom:content". Such text is intended to be presented to humans in a readable 
fashion. The restriction of the content of "atom:summary" and the "type" 
attribute is a restriction of Atom [RFC4287].

An "atom:content" element in an OPDS Catalog Entry either contains or links to 
a description, summary, abstract, or excerpt of the Publication. The behavior 
or "atomOutOfLineContent" and the "src" attribute is defined in Section 4.1.3 
of [RFC4287].

If an OPDS Catalog Entry includes both "atom:content" and "atom:summary", the 
"atom:content" SHOULD NOT be included in the Partial Catalog Entry. Both 
elements SHOULD be included in the Complete Catalog Entry.
"""

Original comment by abdela...@gmail.com on 18 Aug 2010 at 5:33

GoogleCodeExporter commented 9 years ago 
Roger: Please propose RNC additions to express:

"""
An "atom:summary" element in an OPDS Catalog Entry MUST use a "type" attribute 
of "text" and the content MUST NOT contain child elements. 
"""

Original comment by abdela...@gmail.com on 18 Aug 2010 at 8:28

GoogleCodeExporter commented 9 years ago 
    # Here we override Atom to account for html abuse in the summary element,
    # restricting it in OPDS Catalog to text:
    atomSummary = 
      element atom:summary {
        atomCommonAttributes,
        attribute type { "text" },
        text
     }   

(still interested in feedback)

Original comment by abdela...@gmail.com on 18 Aug 2010 at 8:29