Dear all,
Please find below my LC comments.
Jean-Jacques Moreau.
------------------
draft-holl.nbeck-ietf-xml-guidelines-06.txt
LC Comments
Overall, a job well done! Specific comments below.
Section 1.2 (Scope)
"the exclusive use of XML as the data representation"
Shouldn't this say that XML can be used to represent
both data AND protocol elements?
Section 3 (XML Alternatives)
"; mechanims such as XML merely add bloat"
Insert: "for these protocols, "
between: ";" and: "mechanisms".
"RFC 3252... bloat"
I am still of the opinion that the sentence should be
deleted.
"which are not visible"
Replace by: "which are not human readable".
Section 4.4 (XML Declarations)
"Note that XML Declaration is not part of the XML document's
Information Set"
I thought it was an infoset property on the document/root
element?
Section 4.6 (Comments)
The following questions comes to mind: what about
forwarding? I.e. what if the receiver is an intermediary
(that also does some processing on the message):
should it forward comments? can it ignore them when
forwarding?
The same question also applies to Processing Instructions
(section 4.5).
Section 4.7 (Validity and Extensibility)
"XML based protocol specification should thus
explicitely describe extension mechanisms and
requirements to recognize or ignore extensions."
I suggest adding: "Some protocols define such
a mechanism, e.g. SOAP's mustUnderstand attribute."
Section 4.8.1 (Namespace and attributes)
"<ns1:fox a="xxx" ns1:b="qqq"
xmlns="http://example.org"/>
<fox a="xxx" ns1:b="qqq"
xmlns="http://example.org"; xmlns:ns1="http://example.org"/>"
Didn't you mean to have only one of the above two examples?
Otherwise, the reader is not sure which "a" you are
referring to in the next paragraph.
Also, the first example misses the "xmlns:n1" declaration;
and the second example misses "ns1" before "fox".
"bound to namespaces which are identical"
To make things really clear, I suggest adding:
"For example, the following two examples are
discouraged:
<ns1:fox a="xxx" a="yyy"
xmlns="http://example.org";
xmlns:ns1="http://example.org"/>
<ns1:fox ns1:a="xxx" ns2:a="yyy"
xmlns="http://example.org";
xmlns:ns1="http://example.org";
xmlns:ns2="http://example.org"/>"
"XSLT language: while attributes" and later "they are prefixed"
The transatition would read better with: "XSLT
language: attributes..." and "but they are prefixed".
Otherwise, one thinks "while" applies to "language".
Section 4.9 (Element and attribute design considerations)
"or digital signature)."
Add: "It also implies additional overhead to fetch and
apply the corresponding schema."
Section 4.10 (Binary data and text)
"is best for large quantities of data."
Add: "This does not necessarily mean that entire schema
processing needs to be performed, simply that typing via
base64 must be supported." I think this is an important
consideration.
Section 4.11 (Incremental processing)
"browsers which incrementatlly render HTML pages"
Also add a reference to Jabber, which IMO is
precisely an example of interspersed multiple
interactions.
Section 4.16 (Interaction with IANA)
"application/xml"
Why not also "application/xml+protocol_name", which would
clearly indicate this is protocol data, to be handled
as such, but could as well be rendered in a browser?
Overall comment
It is difficult to find recommendations
at first glance. One has to read the whole text and
carefully annotate them. Maybe some special markup,
or the use of capital "MAY", "MUST", etc. could be
used to clearly differentiate recommendations from
the surrounding text? Given the targetted readership
(protocol designers) and proposed status of this
recommendation (BCP), I would consider this as a
significant comment.