Subject: PaceContentAndSummaryDistinct

From: Kevin Marks <[email-masked]>
Date: Sat, 14 May 2005 09:36:31 -0700

After seeing 'in the wild' what I consider badly-formed Atom feeds, 
where both the atom:summary and atom:content contain identical 
abbreviated entry text, I realised that the spec does not make this 
clear.
As this is a key advantage of Atom, I thought it best to make this 
explicit, hence:

http://www.intertwingly.net/wiki/pie/PaceContentAndSummaryDistinct

I appreciate this is late, but I recall a long discussion of this early 
on, and I do want to preserve this distinction, as if it can no longer 
be relied on a key advantage of Atom for feed processors is lost.

---

From: Antone Roundy <[email-masked]>
Date: Sat, 14 May 2005 10:59:00 -0600

On Saturday, May 14, 2005, at 10:36  AM, Kevin Marks wrote:
> I appreciate this is late, but I recall a long discussion of this 
> early on, and I do want to preserve this distinction, as if it can no 
> longer be relied on a key advantage of Atom for feed processors is 
> lost.
>
Clarifying this point is a good idea.  However, "The content of 
atom:content MUST be a complete representation of the entry." isn't 
quite right, because atom:content doesn't contain the metadata found in 
other children of atom:entry.  Here's another idea:

The "atom:content" element either contains or links to the full content 
of the entry. When publishing less than full content, atom:summary MUST 
be used instead. The content of atom:content is language-sensitive.

---

From: "A. Pagaltzis" <[email-masked]>
Date: Sat, 14 May 2005 20:02:44 +0200

> >http://www.intertwingly.net/wiki/pie/PaceContentAndSummaryDistinct

+1

* Antone Roundy <[email-masked]> [2005-05-14 19:10]:
> atom:content MUST be a complete representation of the entry."
> isn't quite right, because atom:content doesn't contain the
> metadata found in other children of atom:entry.

Agreed also.

> The "atom:content" element either contains or links to the full
> content of the entry. When publishing less than full content,
> atom:summary MUST be used instead. The content of atom:content
> is language-sensitive.

-1, this wording is not explicit about the intent of atom:content.

How about:

    The "atom:content" element either contains or links to the
    full content of the entry. An "atom:entry" containing an
    "atom:content" element MUST be a complete representation of
    the entry. If the "atom:entry" is not intended to be a
    complete representation of the entry, you MUST use
    "atom:summary" instead. The content of "atom:content" is
    language-sensitive.

Regards,
-- 
Aristotle

---

From: Graham <[email-masked]>
Date: Sat, 14 May 2005 19:44:38 +0100

> http://www.intertwingly.net/wiki/pie/PaceContentAndSummaryDistinct

I support the sentiment, but the way it's written is awful. We could  
just change:

   The "atom:content" element either contains or links to the content  
of the entry

To:

content of the entry

(or "complete", or the adjective of your choice)

Graham

---

From: Martin Duerst <[email-masked]>
Date: Sun, 15 May 2005 21:24:55 +0900

+1 here, in whatever wording turns out to be best.

Regards,   Martin.

 >> After seeing 'in the wild' what I consider badly-formed Atom feeds, 
where both the atom:summary and atom:content contain identical abbreviated 
entry text, I realised that the spec does not make this clear.
 >> I appreciate this is late, but I recall a long discussion of this early 
on, and I do want to preserve this distinction, as if it can no longer be 
relied on a key advantage of Atom for feed processors is lost.
 >Clarifying this point is a good idea.  However, "The content of 
atom:content MUST be a complete representation of the entry." isn't quite 
right, because atom:content doesn't contain the metadata found in other 
 >The "atom:content" element either contains or links to the full content 
of the entry. When publishing less than full content, atom:summary MUST be 
used instead. The content of atom:content is language-sensitive.

---

From: Thomas Broyer <[email-masked]>
Date: Sun, 15 May 2005 16:57:45 +0200

+1

...but isn't the "MUST use atom:summary" leading to misinterpretation as 
of title-only feeds? In that it might be understood as "you MUST use one 
of atom:content or atom:summary"

-- 
Thomas Broyer

---

From: Tim Bray <[email-masked]>
Date: Sun, 15 May 2005 10:24:53 -0700

On May 14, 2005, at 11:02 AM, A. Pagaltzis wrote:

>     the entry.

-1

What does "complete" mean?  This is untestable and semantically fuzzy.  
I think anything stronger than "is intended to contain the full 
content" is just not workable. -Tim

---

From: "A. Pagaltzis" <[email-masked]>
Date: Sun, 15 May 2005 23:16:17 +0200

* Thomas Broyer <[email-masked]> [2005-05-15 17:10]:
> ...but isn't the "MUST use atom:summary" leading to
> misinterpretation as of title-only feeds? In that it might be
> understood as "you MUST use one of atom:content or
> atom:summary"

Yes, you’re right. I’m not sure what the best way to address that
would be; maybe a qualification like “If the "atom:entry" is not
intended to be a complete representation of the entry, you MUST
instead use "atom:summary" to carry content.” But that is clusmy,
I don’t like it.

* Tim Bray <[email-masked]> [2005-05-15 19:35]:
> -1
> 
> What does "complete" mean?  This is untestable and semantically
> fuzzy. I think anything stronger than "is intended to contain
> the full content" is just not workable.

In terms of formal verifiability of feed conformance, you are
right. In fact, in those terms, there is no way we can clarify
the difference between the two elements, at all. Do you suggest
that this be left to the implementor’s guide?

Personally, I think the spec should try to make an attempt to
nail this down. Maybe the right approach would rather be
something along these lines?

    An "atom:entry" MUST NOT have both an "atom:content" and an
    "atom:summary" element with identical content.

That is a formally verifiable criterion, at least.

Regards,
-- 
Aristotle

---

From: Thomas Broyer <[email-masked]>
Date: Mon, 16 May 2005 00:38:07 +0200

>    "atom:summary" element with identical content.
You're right, +1 to this

-- 
Thomas Broyer

---

From: Graham <[email-masked]>
Date: Mon, 16 May 2005 00:03:05 +0100

-1

It might solve this exact problem, but in the general case it makes  
no sense. Let's say I put the first sentence of each post in  
atom:summary. What happens when I post a one sentence entry?

Graham

---

From: "A. Pagaltzis" <[email-masked]>
Date: Mon, 16 May 2005 01:16:21 +0200

* Graham <[email-masked]> [2005-05-16 01:10]:
> Let's say I put the first sentence of each post in

Then you must not put it in the summary. And this is my opinion
independent of the pace.

An even half-way intelligent user agent would do something like
display a “read more” link or button when it displays a summary,
to alert the user that there is more to be read, either at the
atom:link[@rel='alternate'] location or in a supplied
atom:content.

Would that be applicable to your one-sentence entry?

Regards,
-- 
Aristotle

---

From: Eric Scheid <[email-masked]>
Date: Mon, 16 May 2005 11:20:58 +1000

+1

---

From: "A. Pagaltzis" <[email-masked]>
Date: Mon, 16 May 2005 05:02:42 +0200

* Graham <[email-masked]> [2005-05-16 01:15]:
> It might solve this exact problem, but in the general case it
> makes no sense.

Besides my point in the other mail, I wanted to further address
this.

It does make sense in the general case, in my opinion. A feed
producer is expected to pick the element that reflects the
payload’s nature; this requirement would prevent them from just
sticking the same payload in both elements and letting the
aggregator sort it out.

On a more abstract level, it says “atom:summary and atom:content
are not the same thing” in formally verifiable terms.

It does not express the exact role of each element, but that is
unenforcable anyway. OTOH, it forces feed producers to pick one
element or the other when they only have one piece payload; and
it can reasonably be assumed that they’ll pick as intended. So it
seems to me that it is as close as the spec can get to enforcing
correct usage of the elements.

I’m not wedded to the proposal, but after thinking about it for a
while, I believe it actually makes more sense than it seems to at
first blush.

Regards,
-- 
Aristotle

---

From: "James Tauber" <[email-masked]>
Date: Mon, 16 May 2005 11:41:06 +0800

On Mon, 16 May 2005 01:16:21 +0200, "A. Pagaltzis" <[email-masked]>
said:
> display a "read more" link or button when it displays a summary,

I think this is the key criterion albeit not a particularly formal one.

Which got me thinking: say I provide both a summary-only feed and a
full-content feed.

I believe it is reasonable to:

 1. include a summary element in my full-content feed in addition to the
 content element; and
 2. have some (short) entries in my summary-only feed which contain a
 content element but no summary.

In other words:

 1. "full-content feed" doesn't preclude the existence of a summary
 element but there will never be a summary element without a content
 element.
 2. "summary-only feed" really means that the included summary/content
 won't exceed some arbitrary length. If the content is short enough to
 fit this, I'll use a content element, even though this is a
 "summary-only" feed because the content is complete---there is no "read
 more".

James
-- 
  James Tauber               http://jtauber.com/
  journeyman of some    http://jtauber.com/blog/

---

From: "A. Pagaltzis" <[email-masked]>
Date: Mon, 16 May 2005 05:59:56 +0200

* James Tauber <[email-masked]> [2005-05-16 05:45]:
>  1. include a summary element in my full-content feed in
>  addition to the content element; and

Absolutely it is. F.ex, user agents could provide the summary in
addition to the title of an entry in a feed overview pane, and
display either the atom:content or whatever is located at the
atom:link[@rel='alternate'] URL when you click an entry.

Compare NetNewsWire’s widescreen view.

> [...] In other words: [...]
> 
>  2. "summary-only feed" really means that the included
>  summary/content won't exceed some arbitrary length. If the
>  content is short enough to fit this, I'll use a content
>  element, even though this is a "summary-only" feed because the
>  content is complete---there is no "read more".

Indeed.

These are all reasons that convince me that within possibility
the spec really should try to enforce the distinction: it is an
extraordinarily valuable feature of the format for consumers if
applied consistently.

Regards,
-- 
Aristotle

---

From: Kevin Marks <[email-masked]>
Date: Mon, 16 May 2005 15:43:43 -0700

> content" is just not workable. -Tim

Tim, that is exactly the point.

When parsing RSS <description>, there is no way to know if what is 
there is complete or an extract. Atom rightly expresses these as 
semantically distinct entities. There isn't a good way to distinguish 
them algorithmically, so we really need explicit language in the spec 
making this clear.
It needs human validation, as it can't be done by code, but it needs to 
be in the spec so we can point implementers to it, or better, that they 
see it and realise why there are 2 distinct elements for these 
purposes.

Putting abbreviated forms in both is the semantic pollution; if an 
entry is brief enough to be unsummarizable, having the same in both 
summary and content is perhaps legitimate, but if making the 'not the 
same' requirement explicit requires that very short entries have no 
summary, that works and increases feed consistency.

The difficulty comes when people view the feed content as something 
distinct from the content of the entry itself; in that case we want 
them to use atom:summary rather than atom:content. Just saying 'they 
can't be the same' is insufficient; the reason they are distinct needs 
to be there in the specification too.
My initial language may be clumsy or overdone, but this requires a MUST 
rather than a SHOULD if the content/summary elements are to remain 
useful and distinct.