Bill de hÓra wrote:
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.
Correct. In 1.2, how about "A complete schema appears in Appendix B."
>** 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.
I am concerned that any extension element in the examples will create a procedural issue. I am also concerned that the target audience for a prefixed example would be rather small.
** 2. Atom Documents
p5: this paragraph can be struck without loss of meaning.
reason: adds no specification value.
Agree.
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.
'resolution' is a little sloppy.
How about this:
[[[
Atom allows the use of IRIs [RFC3987], as well as URIs [RFC3986]. IRIs can easily be converted to URIs, and every URI is an IRI, so any URI can be used where an IRI is needed.. When comparing IRIs serving as atom:id values, they MUST NOT be converted to URIs. By definition,
]]]
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.
Yes, but this is as specified by RFC3987, section 5.1, p4.
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).
Agree.
** 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.
Agree.
** 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.
Tim covered this.
** 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.
Agree.
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.
Agree.
** 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.
Agree.
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.
Agree
** 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.
Agree.
** 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)*)) }"
Agree.
** 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.
We shouldn't be at all. We should ditch this reference and the sentence that refers to it.
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:
ABNF is required to understand the spec, because we refer to rules from other specs.
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.
OK
** Replace specification keywords in lowercase (argghh!)
OK.
