Hi editors,
Comments and observations on the 07 draft.
** RNC Schema
- is valid rnc
- the schema and the fragments appear to be consistent.
- both examples validate according to the supplied schema
- the xhtml fragments in 4.1.3.4 validate when embedded as specified.
- in 6.4; simple and extension schema forbid the use of the atom namespace as the top level element in the extension. This is a very common RNG idiom and I imagine the text should reflect the constraint assuming that's the consensus of the WG. Note that it cannot generally be represented in WXS; for example, Trang will convert it to a looser xsd:any constraint.
- in 6.4; extension schema allow the use of the atom namespace as child elements of the extension. I do not recall this being discussed, but personally am +1 to it.
- I believe atomfeed and
replace: [[[ App B Collected RELAX NG Compact Schema ]]]
with: "App B RELAX NG Compact Schema"
reason: not all the schema is presented in fragment form, so the title is incorrect.
** 1. Introduction
p2. the last sentence requires a for-example or should be struck.
reason: qualify what 'other purposes' might be.
** 1.1 Examples:
Please use a namespace prefix for both or at least one of the examples.
reason: 1) default namespaces are not robust (I offer requirement of xhtml:div as evidence), examples in XML formats should not propagate the practice. 2) example markup is not consistent with naming convention used to call out specified elements.
Please add a element property to an entry that is not from the format (ie Dublin Core)
reason: demonstrate what extensible indicates upfront.
** 2. Atom Documents
p5: this paragraph can be struck without loss of meaning.
reason: adds no specification value.
p8: replace:
[[[
Atom allows the use of IRIs [RFC3987], as well as URIs [RFC3986]. For resolution, IRIs can easily be converted to URIs. When comparing IRIs serving as atom:id values, they MUST NOT be converted to URIs. By definition, every URI is an IRI, so any URI can be used where an IRI is needed.
]]]
with the following:
"Atom allows the use of IRIs [RFC3987], as well as URIs [RFC3986]. By definition, every URI is an IRI, so any URI can be used where an IRI is needed. Note:
1. For purposes of resolution, IRIs MAY be converted to URIs.
2. For purposes of comparison, where IRIs act as atom:id values, they MUST NOT be converted to URIs."
Also, if 'resolution' is a term taken from some spec it should be called out as such.
reason: p8 does not read clearly enough to provide implementor guidance.
ob: I think this indicates an implementor burden of using IRIs. I need to write conversion code differently depending on whether I'm resolving or comparing.
p10: remove the following clause: [[[but may be defined by an extension to Atom.]]]
reason: the caveat adds no specification value and provides questions without answers (does 'may' mean 'might' above? defined by who? etc).
** 3.1.1 The "type" Attribute
replace:
[[[
Note that MIME media types [RFC2045] are not acceptable values for the "type" attribute.
]]]
with:
"MIME media types [RFC2045] MUST NOT be used as values for the "type" attribute."
reason: state the specification as specification not as a side note.
** 3.1.1.3 XHTML
replace
[[[
The following example assumes that the XHTML namespace has been bound to the "xh" prefix earlier in the document:
]]]
with
"Note: the following example is not well formed unless the XHTML namespace has been bound previously to the "xh" prefix in the document:"
reason: clearly indicate what conformance prefix binding entails.
** 4.1.1 The "atom:feed" Element
replace:
[[[
* atom:feed elements MUST contain exactly one atom:author element, UNLESS all of the atom:feed element's child atom:entry elements contain an atom:author element. atom:feed elements MUST NOT contain more than one atom:author element.
]]]
with:
"* atom:feed elements MUST contain an atom:author element, UNLESS all of the atom:feed element's child atom:entry elements contain an atom:author element.
* atom:feed elements MUST NOT contain more than one atom:author element."
reason: give each spec its own bullet point.
replace:
[[[
* atom:feed elements MUST NOT contain more than one atom:link element with a rel attribute value of "alternate" that has the same type attribute value. If a feed's atom:link element with type="alternate" resolves to an HTML document, then that document SHOULD have a autodiscovery link element [Atom-autodiscovery] that reflects back to the feed. atom:feed elements MAY contain additional atom:link elements beyond those described above.
]]]
with:
"* atom:feed elements MUST NOT contain more than one atom:link element with a rel attribute value of "alternate" which have the same type attribute value.
* If a feed's atom:link element with type="alternate" resolves to an HTML document, then that document SHOULD have a autodiscovery link element [Atom-autodiscovery] that reflects back to the feed.
* atom:feed elements MAY contain additional atom:link elements with values of the rel attribute other than 'alternate' and 'self'."
reason: give each spec its own bullet point. Change "that has" to "which have" as we're dealing with plurals.
** 4.1.2 The "atom:entry" Element
replace:
[[[
* atom:entry elements MUST contain exactly one atom:author element, unless the atom:entry contains an atom:source element which contains an atom:author element, or, in an Atom Feed Document, the atom:feed element contains an atom:author element itself. atom:entry elements MUST NOT contain more than one atom:author element.
]]]
with:
"* atom:entry elements MUST contain exactly one atom:author element, unless the atom:entry contains an atom:source element which contains an atom:author element, or, in an Atom Feed Document, the atom:feed element contains an atom:author element itself.
* atom:entry elements MUST NOT contain more than one atom:author element."
reason: give each spec its own bullet point.
replace:
[[[
* atom:entry elements that contain no child atom:content element MUST contain at least one atom:link element with a rel attribute value of "alternate". atom:entry elements MUST NOT contain more than one atom:link element with a rel attribute value of "alternate" that has the same combination of type and hreflang attribute values. atom:entry elements MAY contain additional atom:link elements beyond those described above.
]]]
with:
"* atom:entry elements that contain no child atom:content element MUST contain at least one atom:link element with a rel attribute value of "alternate".
* atom:entry elements MUST NOT contain more than one atom:link element with a rel attribute value of "alternate" which have the same combination of type and hreflang attribute values.
* atom:entry elements MAY contain additional atom:link elements with values of the rel attribute other than 'alternate'."
reason: give each spec its own bullet point. Change "that has" to "which have" as we're dealing with plurals.
** 4.2.7 The "atom:id" Element
replace:
[[[
Because of the risk of confusion between IRIs that would be equivalent if dereferenced, the following normalization strategy is strongly encouraged when generating atom:id elements:
]]]
with:
"Because of the risk of confusion between IRIs that would be equivalent if dereferenced, the following normalization strategy SHOULD be applied when generating atom:id elements:"
reason:
reason: prefer operational text; strongly encouraged sounds very like a SHOULD.
** 6.4.1 Simple Extension Elements
add:
add to end of para
"simpleExtensionElement =
element * - atom:* {
text
}"
** 6.4.2 Structured Extension Elements
"structuredExtensionElement =
element * - atom:* {
(attribute * { text }+,
(text|anyElement)*)
| (attribute * { text }*,
(text?, anyElement+, (text|anyElement)*))
}"** General **
** references
[Atom-autodiscovery] Pilgrim, M., “Atom Feed Autodiscovery”, work-in-progress, August 2004.
I'm not sure Atom need be depending on this document. I probably missed that thread where we said it was ok.
add to the informative references:
[RELAX-NC] OASIS Technical Committee: Committee Specification 21, “RELAX NG Compact Syntax”, November 2002.
fyi:http://www.oasis-open.org/committees/relax-ng/compact-20021121.html
** ABNF
Drop.
in 1.2, remove:
[[[
Some sections of this specification are illustrated with Augmented Backus-Naur Form (ABNF), a format used to represent permissible strings in a protocol or language, as defined in [RFC2234].
]]]
in 9.1 remove:
[[[
[RFC2234] Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF”, RFC 2234, November 1997.
]]
reason: ABNF is used in one place:
4.2.9.2 The "rel" Attribute, p1
and referred to in 3.3. It's incidental enough to be dropped.
** Figures
Please add figure captions for all samples, bnf and rnc fragments. If you require someone to do this, I will do it.
** Replace specification keywords in lowercase (argghh!)
2. p10, "but may be defined by"
4.1.3.2, p1 "That is to say, the content may be retrievable usingThat is to say, the content may be retrievable using", "or it may be contained within atom:content, but not both."
4.1.3.3, bullet 2 " The XHTML div MUST contain XHTML text and markup that could validly"
bullet 4 "the content of atom:content may include child elements"
bullet 6 "the Base64 encoding may be preceded"
4.2.9.2 p4 bullet 4 "large in size and may require special handling"
5.1, p3, "the document element must not cause an Atom Processor"
6.2 p1 "versions of this specification may add new elements"
6.3 p1 "It may be the case" - replace 'may' with 'might' here
8.1 p1 "to receiving software, which may process it."
8.2 p2 "other elements may also have negative security properties" - replace 'may' with 'might' here
note: in some cases, may might be being used to indicate to indicate something is possible rather than something is permissable, I can determine that for sure in only two cases above; since may has a technical meaning, the editors should review the text and replace may with might as they see fit to avoid the idiomatic use of may as might.
