On Jan 30, 2005, at 7:58 AM, Bill de hÓra wrote:
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
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
+1
** 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.
-1. I think the text about "software MAY display..." adds to the clarity and usefulness of the spec.
** 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.
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.
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.
+1
** 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
+1 on all these typographical suggestions.
** 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.
+1. Or even better, remove "version"
** 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.
+1
** 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.
-1. This has been beaten to death.
** 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.
Without going back and reading the current text, this is very clear and readable.
** 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.
+1
** 4.21 The "atom:info" Element
proposal: Given all the other feed metadata available, I think this element could be dropped. (pace forthingcoming)
+1
** 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)
+1
** @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.
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
