Subject: Obs on format-05

From: Bill de hÓra <[email-masked]>
Date: Sun, 30 Jan 2005 15:58:33 +0000

Hi editors,

My overall impression of 05 is positive. Once extensibility and security 
are tied down, I think we're close to ready to remove the "do no deploy" 
constriction and let the world have at.

Here are some detailed obs on reading the latest draft.

** 1. Introduction

I don't think further discussion on motivation or principles is needed; 
on that basis the "[[more motivation/design principles]]" memo could be 
struck.

** 1.4 Notational Conventions

Replace:
[[[
This specification uses XML Namespaces [W3C.REC-xml-names-19990114] to 
uniquely identify XML elements and attribute names.
]]]

with:
"This specification uses XML Namespaces [W3C.REC-xml-names-19990114] to 
uniquely identify XML elements."

reason: we don't prefix Atom attributes.

Replace:
[[[
Note that the choice of any namespace prefix is arbitrary and not 
semantically significant.
]]]

with:
"Note that the choice of any namespace prefix is arbitrary."

reason: semantically significant is redundant and/or not true depending 
on your processing .

** 3.1.1 "type" Attribute

Replace:
[[[
If the value is "TEXT", the content of the Text construct MUST NOT 
contain child elements. Such text is intended to be presented to humans 
in a readable fashion. Thus, software MAY display it using normal text 
rendering techniques such as proportional fonts, white-space collapsing, 
and justification.
]]]

with:
"If the value is "TEXT", the content of the Text construct MUST NOT 
contain child elements. Such text is intended to be presented to humans 
in a readable fashion."

(I have more to say on @type later)

reason: we don't need to tell people what they can do with TEXT once we 
tell them what it is.

** 3.2.3 The "atom:email" Element
[[[
The "atom:email" element's content conveys an e-mail address associated 
with the persons.
]]]

typo: the last word should be "person".

** 3.5.1 Dereferencing Identity Constructs

[[[
... and it is suggested that the Identity construct be stored along with 
the associated resource.
]]]

problem: I didn't understand what that meant.

Replace:
[[[
Because of the risk of confusion between URIs that would be equivalent 
if dereferenced, the following normalization strategy is strongly 
encouraged when generating Identity constructs:
]]]

with:
"Because of the risk of confusion between URIs that would be equivalent 
if dereferenced, the following normalization strategy SHOULD be applied 
  when generating Identity constructs:"

reason: change the passage a become a specification.

** 3.5.2 Comparing Identity Constructs

Replace:
[[[
For example, "http://www.example.org/thing", 
"http://www.example.org/Thing", "http://www.EXAMPLE.org/thing" and 
"HTTP://www.example.org/thing" will all be considered different 
identifiers, despite their differences in case.
]]]

with:
"For example:

    http://www.example.org/thing
    http://www.example.org/Thing
    http://www.EXAMPLE.org/thing
    HTTP://www.example.org/thing

represent 4 distinct identifiers, due to differences in case."

reason: visual clarity, use of different in two contexts, one more 
accurately replaced with distinct.

Replace:
[[[
Likewise, "http://www.example.com/~bob", "http://www.example.com/%7ebob" 
and "http://www.example.com/%7Ebob" will all be considered different 
identifiers, because URI %-escaping is significant for the purposes of 
comparison.
]]]

with:

"Likewise,

   http://www.example.com/~bob
   http://www.example.com/%7ebob
   http://www.example.com/%7Ebob

represent 3 distinct identifiers, because URI %-escaping is considered 
significant for comparison purposes."

reason: visual clarity, consistency with changes in the preceding para 
above.

** 4.1.1 The "version" Attribute

It bugged me that the version identifier has whitespace (some kind of 
personal neurosis no doubt).

Replace:
[[[
the content of this attribute is unstructured text
]]]

with:
"the content of this attribute is unstructured text and is not intended 
for interpretation by software agents."

reason: it's evidently structured (I can read it) and I'm sure software 
will want to be abale to distinguish from another version as a string, 
but it's not intended to be interpreted with respect to another version 
for version control purposes.

** 4.13.3 The "label" attribute

Replace:
[[[
The "label" attribute provides a human-readable label that may be 
displayed in end-user applications.
]]]

with:
"The "label" attribute provides a human-readable label for display in 
end-user applications."

reason: eliminate use of 'may' in a non-spec context, plus I don't see 
the need to spec anything here.

** 4.15 The "atom:content"

[[[
  atom:entry elements MUST contain zero or one atom:content elements.
]]]

proposal: I would like this loosened to zero or more (a Pace is 
forthcoming). I have use cases to ship content about in Irish and 
English form - Zero or One means I need a private content model to 
support that.

** 4.15.2 The "src" attribute

Can I suggest the following:

"atom:content MAY have a "src" attribute, whose value MUST be a URI 
reference [RFC2396bis].

Content can be contained within atom:content or retrieved using a "src=" 
URI, but not both. Thus, If the "src" attribute is present, atom:content 
MUST be empty - software MAY instead dereference the URI to retrieve the 
content.

When the "src" attribute is present, the "type" attribute SHOULD be 
provided and MUST be a MIME media type [RFC2045]. If the value of type 
begins with "text/" or ends with "+xml", the "src" attribute SHOULD NOT 
be present - in that case content SHOULD be embedded.

The value of the type atribute is advisory - if a media type is also 
provided upon dereferencing the src URI then the server-provided media 
type MUST be considered authoritative."

reason: I found the current text confusing and had to read it multiple 
times.

** 4.20 The "atom:generator" Element

Replace:

[[[
The "atom:generator" element's content identifies the software agent 
used to generate a feed, for debugging and other purposes.
]]]

with:
"The "atom:generator" element's content identifies the software agent 
used to generate a feed."

reason: we don't to say what can be done with this metadata.

** 4.21 The "atom:info" Element

proposal: Given all the other feed metadata available, I think this 
element could be dropped. (pace forthingcoming)

** 5 Managing Feed State

proposal: I think this section can be dropped. Also, I'm not sure what 
Pace we have in the pipeline that are going to provide the content. 
(pace forthingcoming)

** 6  Securing Atom Documents
** 10 Security Considerations

proposal: Perhaps we can move everything security related into section 
10 and drop section 6. (pace forthingcoming)

** @type **

The passages in 3.1.1 and  4.15.1 and 4.6.3 around @type are not 
consistent.

In 3.1.1 media types are not an option:
[[[
Note that MIME media types [RFC2045] are not acceptable values for the 
"type" attribute.
]]]

in  4.15.1 and 4.6.3 they are stated as an option.

On re-reading, I'm pretty sure that 3.1.1 could be struck without any 
loss of meaning to the spec, giving the processing model outlined in 
4.15.3. And 4.15.3 could perhaps be moved up to where 3.1.1 is if we 
wanted to retain the notion of a construct for type.

cheers
Bill

---

From: Anne van Kesteren <[email-masked]>
Date: Sun, 30 Jan 2005 17:56:40 +0100

> wanted to retain the notion of a construct for type.

This has been pointed out before. However, all three are different @type
attributes. Their semantics are related to the element they are applied
on.

-- 
  Anne van Kesteren
  <http://annevankesteren.nl/>

---

From: Sam Ruby <[email-masked]>
Date: Sun, 30 Jan 2005 12:12:08 -0500

Bill de hÓra wrote:

[snip]

Lots of good comments.  Many are editorial, and can simply be adopted by 
the editors without an explicit proposal, and for others you indicated 
that a Pace is forthcoming.  I'll comment on a few that I believe 
require a Pace...

> reason: we don't need to tell people what they can do with TEXT once we 

Often times the use of MAY is advisory to the producer.  This is one of 
those cases: if you are expecting mono spaced fonts, you might want to 
consider using either HTML or XHTML and making the markup explicit.

> problem: I didn't understand what that meant.

What we are trying to avoid is people generating unique ids every time a 
feed is fetched, as the real purpose of this element is for correlation 
to prior versions of the feed.

> English form - Zero or One means I need a private content model to 

I realize that you indicate that you intend to write a Pace on this. 
Just be aware that earlier drafts of Atom supported multiple content, 
and a lot of people seemed very motivated to eliminate this.

Are your requirements related to Atom being used for syndication or as a 
protocol?

-Sam Ruby

---

From: Tim Bray <[email-masked]>
Date: Sun, 30 Jan 2005 09:25:50 -0800

> Here are some detailed obs on reading the latest draft.

Excellent, Bill, thanks.

> ** 1. Introduction
>
> I don't think further discussion on motivation or principles is 
> needed; on that basis the "[[more motivation/design principles]]" memo 
> could be struck.

+1

> reason: semantically significant is redundant and/or not true 
> depending on your processing

+1

> contain child elements. Such text is intended to be presented to 
> humans in a readable fashion. Thus, software MAY display it using 
> normal text rendering techniques such as proportional fonts, 
> white-space collapsing, and justification.
> ]]]
>
> with:
> contain child elements. Such text is intended to be presented to 
> humans in a readable fashion."
>
> reason: we don't need to tell people what they can do with TEXT once 
> we tell them what it is.

-1.  I think the text about "software MAY display..." adds to the 
clarity and usefulness of the spec.

> ... and it is suggested that the Identity construct be stored along 
> with the associated resource.
> ]]]
>

I think I do, but it needs work... it's suggesting an implementation 
technique for keeping the atom:id stable across changes in the entry.

> "Because of the risk of confusion between URIs that would be 
> equivalent if dereferenced, the following normalization strategy 
> SHOULD be applied  when generating Identity constructs:"
>

+1

>    http://www.example.org/Thing

+1 on all these typographical suggestions.

> "the content of this attribute is unstructured text and is not 
> intended for interpretation by software agents."
>
> reason: it's evidently structured (I can read it) and I'm sure 
> software will want to be abale to distinguish from another version as 
> a string, but it's not intended to be interpreted with respect to 
> another version for version control purposes.

+1.  Or even better, remove "version"

> the need to spec anything here.

+1

> English form - Zero or One means I need a private content model to 

-1.  This has been beaten to death.

> Content can be contained within atom:content or retrieved using a 
> "src=" URI, but not both. Thus, If the "src" attribute is present, 
> atom:content MUST be empty - software MAY instead dereference the URI 
> to retrieve the content.
>
> begins with "text/" or ends with "+xml", the "src" attribute SHOULD 
> NOT be present - in that case content SHOULD be embedded.
>

Without going back and reading the current text, this is very clear and 
readable.

> reason: we don't to say what can be done with this metadata.

+1

> element could be dropped. (pace forthingcoming)

+1

> Pace we have in the pipeline that are going to provide the content. 

+1

> wanted to retain the notion of a construct for type.

I'm definitely -1 on losing 3.1.1, the text construct is a hard-won 
compromise and seems to cause no-one any pain.  Several people have 
pointed out that having 3 diffferent "type" attributes, meaning 
different things, is a source of confusion. -Tim

---

From: Robert Sayre <[email-masked]>
Date: Sun, 30 Jan 2005 12:43:42 -0500

> -1.  This has been beaten to death.

Agree. -1. Bill needs a private content model. Removing the content 
model from Atom will not fix that. I suggest something like 
"text/bill+xml". Making general-purpose feeds available where one 
consumer will only ever use half of the content is bad practice. Use two 
resources. If we were looking for a way to make the bandwidth problem 
much, much worse, this would be one way.

Robert Sayre

---

From: Tim Bray <[email-masked]>
Date: Sun, 30 Jan 2005 10:15:02 -0800

> and a lot of people seemed very motivated to eliminate this.

To be fair, it was the original "multipart/alternative" proposal that 
people (including me) wanted to nuke.  Having said that, unless there a 
wave of real implementors saying "we need multiple <content>", I'm 
probably -1 on this kind of experimental new feature. -Tim

---

From: Bill de hÓra <[email-masked]>
Date: Sun, 30 Jan 2005 23:55:13 +0000

> different things, is a source of confusion. -Tim

Fair enough; I think the sentence I left in above might need to be 
struck as media types are allowed values in some cases.

cheers
Bill

---

From: Bill de hÓra <[email-masked]>
Date: Sun, 30 Jan 2005 23:49:52 +0000

> consider using either HTML or XHTML and making the markup explicit.

Ok, I'll withdraw that request.

> Are your requirements related to Atom being used for syndication or as a 

As a data format for content publication, so I guess it leans closer to 
syndication. I'll have to think about it more given Tim and Robert's 
objection (arguably what I'm looking for counts as a corner-case).

cheers
Bill

---

From: Mark Nottingham <[email-masked]>
Date: Sun, 30 Jan 2005 19:11:07 -0800

Hey Bill,

Thanks for the detailed, well-justified and precise comments; this is a 
very helpful format to submit them in (hint, hint). Some selective 
feedback;

On Jan 30, 2005, at 7:58 AM, Bill de hÓra wrote:

> depending on your processing .

I tend to disagree; we can choose to say that it's not significant if 
we don't want it to be, and even if it is redundant, it's good to make 
sure this often-misunderstood point gets home.

> reason: we don't need to tell people what they can do with TEXT once 

I could go either way on this; I tend to agree with you, but it's not a 
big deal.

> problem: I didn't understand what that meant.

With you there, but I know this was a contentious point.

> reason: change the passage a become a specification.

Consensus IIRC was to make this non-normative text, and that's where 
personally I'd like to see it stay.

> another version for version control purposes.

I think we should wait for a definite direction WRT versioning and 
extensibility here.

> reason: we don't to say what can be done with this metadata.

Doesn't seem harmful to give examples of what this might be used for; 
what if an 'e.g.' were inserted before 'for'?

> Pace we have in the pipeline that are going to provide the content. 

I had a proposal in e-mail, will put into a Pace.

> 10 and drop section 6. (pace forthingcoming)

Sounds like a good idea, but I don't feel strongly about it if anyone 
wants it the way it is.

Cheers,

--
Mark Nottingham     http://www.mnot.net/

---

From: Bill de hÓra <[email-masked]>
Date: Mon, 31 Jan 2005 09:35:29 +0000

> much, much worse, this would be one way.

I take your point but disagree on the last bit. The bandwidth problem, 
and someone is sure to say "what problem?", is a function of the rate of 
retrieval, not the size of the document. [I could for example, spin a 
bandwidth/size rationale to prejudice against optional/extensible 
metadata.]

cheers
Bill

---

From: Antone Roundy <[email-masked]>
Date: Mon, 31 Jan 2005 11:03:36 -0700

On Sunday, January 30, 2005, at 10:25  AM, Tim Bray wrote:
>> Note that MIME media types [RFC2045] are not acceptable values for 
>> the "type" attribute.
>> ]]]
>>
Given that we're very unlikely to change what's acceptable in the 
various @type attributes, perhaps one of the persons concerned about 
this issue could write a proposal to change the name of one or more of 
these attributes.