Re: rq25 (1.18) review (part I)

Hi Kendall,

I'm taking a pass at your remaining suggestions. Responses / actions are 
inline.

Kendall Clark wrote on 03/05/2007 04:04:54 PM:
> 
> > > Strike the odd adjective "companion" that's used in front of
> > > "protocol". Makes no sense.
> 
> You didn't say anything about this one, Andy. I still think it should 
> be struck.

Duly struck.
 
> > The convention (by scanning some W3C recs) appears to be that all 
> > sections are normative unless stated otherwise; appendices are not 
> > normative unless marker normative.
> 
> That's fine, I suppose, but as I said earlier today, I think the doc 
> should *say* this explicitly, since most readers won't know W3C 
> convention and won't scan W3C recs, as you've done.
> 
> I also think there should be some kind of rule for resolving clashes 
> between normative sections, where the algebra and grammar trump. 
> (And, yes, that's won't *always* be sufficient.)

Checking out a few recs of my own shows a variety of approaches. We're 
going to take discuss and decide which parts of the document should be 
normative/informative at the next telecon. In the meantime I've put in an 
@@ in the introduction to explicitly specify how readers should determine 
which material is normative/informative.

> 
> > The data description is Turtle and outside the spec.
> 
> I don't understand this comment.

The full exchange was (Kendall and then Andy):

"""
 > Strike "used to show each triple explicitly". A spec is *not* a meta-
 > commentary upon itself. There is, IMO, far too much of this kind of
 > self-referential commentary. A specification *specifies*; it does not
 > discuss, converse, comment, or muse.

The data description is Turtle and outside the spec.  It is worth noting 
that 
we are using Turtle in a way that shows every triple explicitly, in 
contrast 
to RDF/XML.
"""

I believe that Andy was responding that "used to show each triple 
explicitly" is not meta-commentary, as it is commenting on Turtle rather 
than on SPARQL. I've changed the wording to:

"""
This document uses the Turtle data format to show each triple explicitly.
"""

> > > IMO, we should not define terms used from another spec and then
> > > *rename* them in this spec. This is
> > > just confusing. "IRI" -> "RDF URI reference"; and "datatype IRI" ->
> > > "datatype URI". If we're going to do this -- and I'd prefer we 
> > didn't
> > > -- it should be more explicitly marked as such. Putting this into 
> > two
> > > parenthetical phrases -- which suggests that that content is
> > > secondarily important -- is likely to cause confusion.
> >
> > This is the "Document Conventions" section and it is importing 
> > terminology from elsewhere.
> 
> Yes, I get that. But in two places the terms are renamed, too, which 
> I think is confusing. A sentence to this effect would suffice: "Two 
> of the terms used from [wherever they come from...] are used with the 
> same meaning but are renamed here: "RDF URI reference" is spelled as 
> "IRI" and "datatype URI" is spelled "datatype IRI" in this document." 
> Or some such.

Except that the meanings are not identical, as explained at the beginning 
of 1.2.4:

"""
The SPARQL language includes IRIs, a subset of RDF URI References that 
omits spaces. Note that all IRIs in SPARQL queries are absolute; they may 
or may not include a fragment identifier [RFC3987, section 3.1]. IRIs 
include URIs [RFC3986] and URLs. The abbreviated forms (relative IRIs and 
prefixed names) in the SPARQL syntax are resolved to produce absolute 
IRIs.
"""

I considered a clause at the end of the parentheticals along the lines of 
", with the changes from URIs to IRIs noted above", but believe the 
section is clearer as is.

> > > "SPARQL implementations may issue warnings..." -- how? Which ones?
> > > There's a lot of talk about
> > > warnings and errors, but no warnings or errors defined. Why not?
> >
> > The local API is free to do what it wants.  The protocol would also 
> > be a way to issue warnings.
> 
> Yeah, I think this is still confusing and problematic. At the very 
> least shouldn't we tally up all the place in the QL spec where it 
> mentions some error or warning, give them all names, and then stick 
> those into the protocol spec? That a local API may do something else, 
> and is undefined by the WG, doesn't really seem at all relevant.

@@Eric@@ I've asked Eric to look at the occurrences of "warning" and 
"error" in the query language document and to hyperlink where appropriate 
and reword where appropriate. In this particular case, Eric, I'd recommend 
striking the entire sentence dealing with warnings - it's simply a 
restatement of what RDF C&AS already states.

> > Some tools don't work with – properly (possibly this is 
> > charset problems).  We've had document corruption problems before :-(
> 
> Ouch. Well, there is a Unicode form for browsers that are broken; I 
> wasn't suggesting "–" explicitly as just reminding about the 
> conventional orthography, which may be implemented in a few diff ways.

In the interests of time and lacking the resources to thoroughly audit the 
document for ranges and Web browsers for the most supported way to express 
en dashes, I've chosen to ignore this orthographic error. If you have the 
resources to address this, I'd be glad to commit the changes.

> > """
> > Blank node labels are scoped to a result set (as defined in "SPARQL 
> > Query Results XML Format") or the graph for the CONSTRUCT query 
> > form. An application writer should not expect blank node labels in 
> > a query to refer to a particular blank node in the data. Use of the 
> > same label within a result set of graph indicates the same blank node.
> > """
> > work better for you?
> 
> Yes, except for the extraneous "of graph" in the last sentence.

Removed "of graph".

> > The use of "may"/"should"/"must" etc in the sense of RFC2119 is 
> > indicated by their use in some emphasized form (bold or capitals 
> > usually, depending on the medium).  They refer to obligations on 
> > the implementations.  We are discussing what SPARQL is, not what an 
> > implementation may/must/should do.  That resides with the protocol 
> > document - it's the request that is executed that has the main 
> > conformance obligation.
> 
> I looked at XQuery, since that seems the obvious analogue. It has a 
> very nice conformance section, where it uses RFC 2119 words. I think 
> it's worth looking at.

@@Eric@@ I've asked Eric to look at the conformance issue.

> > > Last sentence: "may be the empty string" -- huh?
> >
> > "may be empty" ??
> 
> Perhaps, I don't know; but "may be the empty string" is hard to 
> understand. Maybe just "may be an empty string"?

In my background, "the empty string" is preferable to "an empty string." 
That said, I think that "may be empty" is clearest.

> > > And "These allocated blank nodes..." is vague. Which ones?
> >
> > the ones for the list
> 
> If you haven't already, I think you should make that more explicit.

Changed to: "The blank nodes allocated by the collection syntax do not 
occur elsewhere in the query."

> > changed to "short form" like previously.
> >
> > It may be equivalent abstractly but strictly it's not equivalent 
> > because different grammar productions are involved.  "short 
> > form" (sometimes "syntactic sugar") is the term I know to use for 
> > this.
> 
> I think 'syntactic sugar' or 'a shortened, convenience form' are 
> better than 'short form'.

I can live with either. I've changed it to "syntactic sugar" since it 
seems that that wording is acceptable to all three of us.

Lee

> Cheers,
> Kendall
>

Received on Tuesday, 6 March 2007 21:59:49 UTC