Subject: PaceUpdatedDefinition

From: Robert Sayre <[email-masked]>
Date: Fri, 29 Oct 2004 18:52:48 -0400

Hi all,

Another Date-related Pace. Yay!

None of the verbs or nouns in the phrase "bring to the attention of 
subscribers" are defined in the spec, so we managed to reach consensus 
on atom:updated without reaching consensus. This is a proposed 
clarification/alteration/crusher-of-dreams. Choose your favorite 
description.

Robert Sayre

Abstract
-------------------
Alter the definition of atom:updated.

Status
-------------------
Open

Supporters
-------------------
RobertSayre

Rationale
-------------------
The definition of atom:updated is confusing, and causes rational people 
to disagree on its purpose.

The phrase "bring to the attention of subscribers" is inadequate, as it 
depends entirely on the definition of terms. Undefined terms:

* "Bring"
* "Attention"
* "Subscribers" (we use "producer", "consumer",
   and "processor"... this is a new one)

Proposal
-------------------
Replace the first paragraph of the current definitions of atom:updated 
with the following:

    The "atom:updated" element is a Date construct indicating the most
    recent instant in time when a substantive modification to the
    [feed/entry] was made. The value of atom:updated can be changed at
    the producer's discretion.

-------------------

Robert Sayre

---

From: Eric Scheid <[email-masked]>
Date: Sat, 30 Oct 2004 10:53:42 +1000

>   the producer's discretion.

define 'substantive'.

in the spirit of writing spec text, I suggest:

    For example, such changes might not include minor adjustments
    like spelling and grammatical corrections.

e.

---

From: Danny Ayers <[email-masked]>
Date: Sat, 30 Oct 2004 11:57:02 +0200

[I'm back! I think rewording has a change of breaking the logjam]

I like "typically" because it expresses the most common, expected case.

Either:

"such changes would typically not include minor adjustments like
spelling and grammatical corrections."

or

"such changes would typically include minor adjustments like spelling
and grammatical corrections."

We may disagree on which, but the most important thing is to have
everyone reading from the same page, no?

I realise that we don't really want to put behaviour definitions into
the spec, but it might help with the wording to imagine exactly what
behaviour we would expect in a typical client - say RSS Bandit.

Cheers,
Danny.

-- 

http://dannyayers.com

---

From: Bill de hÓra <[email-masked]>
Date: Sat, 30 Oct 2004 14:28:29 +0100

Eric Scheid wrote:

 >  For example, such changes might not include minor
 >  adjustments like spelling and grammatical corrections.

> behaviour we would expect in a typical client - say RSS Bandit.

Folks,

I've had a lot of helpful comments over the last day, but I still 
suspect I'm not getting something fundamental about these two dates. 
Why say "a substantive modification" or add discriminating text, 
when you can say "a change"?

It's not really the client I'd be looking at re behaviour 
definitions. It's whether the producer wants to world's clients and 
intermediaries to know about the change. Suppose we had a UI screen 
for filling out entries:

  Your infammatory title:
    [ Lorem ipsum delor sucks!      ]

  Your rabid entry:
    [ Lorem ipsum delor sit amem... ]
    [                               ]
    [                               ]
    [                               ]
    [                               ]

  Your misleading summary:
    [ This entry is about Java, not ]
    [ pig Latin...                  ]

  [Save changes] [Cancel]  [x] (mark as updated)

If you have 2 change states in the format, it seems to me you have 
to reflect the option to discriminate between them in the UI (unless 
we're talking about UIs that do NLP). But if you had that, you can 
have the back of the UI simply push atom:updated forward based on 
the users selection . I don't then see the need to discrimate change 
states in the format.

cheers
Bill

---

From: Robert Sayre <[email-masked]>
Date: Sat, 30 Oct 2004 10:17:12 -0700

Bill de hÓra wrote:

> Why say "a substantive modification" or add discriminating text, when 
> you can say "a change"?
>
> It's not really the client I'd be looking at re behaviour definitions. 
> It's whether the producer wants to world's clients and intermediaries 
> to know about the change. Suppose we had a UI screen for filling out 
> entries:

I've updated the Pace.

   The "atom:updated" element is a Date construct indicating the most
   recent instant in time when a modification to the [feed/entry] was made. 
   The value of atom:updated can be changed at the producer's discretion, so
   not all modifications result in a changed atom:updated value.

I will include no sentences about "typically" this or that, since the 
choice is entirely up to the producer. Besides, most software will 
probably change atom:updated wiith the most minor changes, as Roger says.

Robert Sayre

---

From: Danny Ayers <[email-masked]>
Date: Sat, 30 Oct 2004 16:25:02 +0200

> the users selection . I don't then see the need to discrimate change

I don't entirely follow, but here's my reading of the situation.
Assuming an entry had already been published, and later the author
goes back to their UI and makes some minor changes.

[Save changes]  [x] (mark as updated)

1. Save changes is clicked, updated checked.
The entry would now go out in the feed with atom:updated changed. When
a client sees this entry it can do a comparison and replace its older
version. The client UI may change the flag of the entry to 'unread' or
make its title italic or whatever.

[Save changes]  [ ] (mark as updated)

2. Save changes is clicked, updated unchecked.

The entry would now go out in the feed with all data exactly as when
previously published, with the exception of whatever changes have been
made to the content.

If the client is subscribed *directly* to the originating feed, then
it may pick up the changes and modify its local copy of the content.
This presumably wouldn't be flagged to the user in any way they would
notice in their general reading. This only works if two assumptions
are made: that entries in more recently published feeds are more
recent; that entry order with the feed is significant.

The biggest problem as I see it is when the client isn't subscribed
directly to the originating feed, a scenario that's becoming more
common (Norm is already on at least two Planets plus PubSub and
Feedster feeds).

There have now been two versions of the entry published which differ
only in their content. There is no longer any guarantee (if there ever
was) that the entries will be received by the client in the order in
which they were published. How is the client to know which version of
the content is current?

The only way around this is with what Bob described, that these
entries are considered equivalent by the publisher so it simply
doesn't matter - any version the client receives will do, whether or
not it is the most recent. The heuristic that the most recently
received is actually the most recent may help, but there are no
guarantees. There hasn't been any acknowledgement from the
anti-modified lobby that this would have to be accepted. Suggestions
that the publisher may lie or that it's guesswork anyhow are
orthogonal red herrings. We have to base the spec on the assumption
that people will follow it, not on indeterminate bad practice.

Resetting the atom:modified value whenever there has been a change to
the entry makes  explicit which is the more recent. The definition of
"a change" isn't such a big deal: basically any difference in the
document fragment corresponding to the entry as interpret by Atom -
the spec could define this is terms of a simple diff on the
element/attribute's content or something based on the infoset.

Cheers,
Danny.

-- 

http://dannyayers.com

---

From: Tim Bray <[email-masked]>
Date: Sat, 30 Oct 2004 08:55:47 -0700

On Oct 30, 2004, at 10:17 AM, Robert Sayre wrote:

>   recent instant in time when a modification to the [feed/entry] was 
> made.   The value of atom:updated can be changed at the producer's 
> discretion, so

s/modifications result/modifications necessarily result/.

But actually, I'm OK with the text in the draft as it is. -Tim

---

From: Graham <[email-masked]>
Date: Sat, 30 Oct 2004 17:00:09 +0100

> clarification/alteration/crusher-of-dreams. Choose your favorite 

While I agree with the terminology problem, this new wording completely 
changes the meaning of the element (reading the original pace, it's 
pretty clear it was only meant for significant updates). Big fat -1.

Graham

---

From: Robert Sayre <[email-masked]>
Date: Sat, 30 Oct 2004 12:13:24 -0400

> s/modifications result/modifications necessarily result/.

Done.

> But actually, I'm OK with the text in the draft as it is. -Tim

I'm OK with my interpretation of the text in the current draft, but not 
with the interpretation of others. A spelling correction may not big 
deal in long pieces like you write, but I tend to write about 10-20 
words per post. A misspelled word can make something I write completely 
unparsable.

Robert Sayre

---

From: Robert Sayre <[email-masked]>
Date: Sat, 30 Oct 2004 12:13:01 -0400

> pretty clear it was only meant for significant updates). Big fat -1.

Graham. Who decides what constitutes a significant update?

Robert Sayre

---

From: Graham <[email-masked]>
Date: Sat, 30 Oct 2004 17:18:55 +0100

On 30 Oct 2004, at 5:13 pm, Robert Sayre wrote:

> Graham wrote:
>
>> While I agree with the terminology problem, this new wording 
>> completely changes the meaning of the element (reading the original 
>> pace, it's pretty clear it was only meant for significant updates). 
>> Big fat -1.
>

For the millionth time, the publisher.

Graham

---

From: Danny Ayers <[email-masked]>
Date: Sat, 30 Oct 2004 18:21:14 +0200

> But actually, I'm OK with the text in the draft as it is. -Tim

Might it be worth adding a note to clarify:

"Where a client receives more than one version of an entry with the
same atom:updated value, it will not be possible to determine which is
the most recently modified version of that entry."

Cheers,
Danny.

-- 

http://dannyayers.com

---

From: Robert Sayre <[email-masked]>
Date: Sat, 30 Oct 2004 13:24:32 -0400

> For the millionth time, the publisher.

OK, I don't see how the current text differs in that respect, but I'll 
try to drive that point home, without mentioning "spelling" in a 
normative section of the spec. How's this:

  The "atom:updated" element is a Date construct indicating the most
  recent instant in time when the [feed/entry] was modified in a way
  the producer considers significant. Ergo, not all modifications
  necessarily result in a changed atom:updated value.

Robert Sayre

---

From: "Roger B." <[email-masked]>
Date: Sat, 30 Oct 2004 12:52:15 -0500

>   necessarily result in a changed atom:updated value.

+1... although I think I liked the last iteration a little better.

--
Roger Benningfield

---

From: Graham <[email-masked]>
Date: Sat, 30 Oct 2004 18:43:29 +0100

>  necessarily result in a changed atom:updated value.

Yes, though I want to flip around the last sentence and say "Only a 
subset of modifications will result in etc".

Graham

---

From: Eric Scheid <[email-masked]>
Date: Sun, 31 Oct 2004 09:28:20 +1000

> necessarily result in a changed atom:updated value.

+1