Re: rq25 (1.18) review (part III)

More editorial ...

 > 8 RDF Dataset
 >
 > I find much of this to be unnecessary (unwanted, really) commentary
 > that could be struck, resulting in a shorter, better spec. The first
 > sentence, at least, is also redundant.
 >
 > "Many RDF data stores hold multiple..." -- so what?
 >
 > What status does the talk of arranging provenance information, say, in
 > the default graph have? That's *one* design pattern, but there are
 > others. It sounds like it should have some normative weight, and it
 > certainly does if anything else in the document has any.

Other people have found examples useful, both at the level of this section and 
as an overall observation/request that more examples should be included.  We 
have to have a balance of needs.

 >
 > In the 2nd paragraph, "...each identified by IRI." -- The same IRI or
 > different ones? This entire sentence is confusing.

Changed to:
"... where each named graph is identified by an IRI."

 >
 > And these seem contradictory: First, "There may be no named graphs;
 > there is always a default graph"; and, second, "A query does not need
 > to involve the default graph..."

The second is about the query; the first about the dataset.  The second 
extract does say query - can you suggest better wording here?

 >
 > This is all confusing and needs to be reworked, IMO.
 >
 > 8.1 Examples of RDF Datasets
 >
 > This section should be struck entirely.
 >
 > 8.2 Specifying RDF Datasets
 >
 > "A query processor may use these IRIs in any way..." -- Which IRIs?
 >
 > 8.2.1 Specifying the Default Graph
 >
 > "This does not put the graph in as a named graph; a query can do this
 > by also specifying..." -- Multiple ambiguities: What does not put the
 > graph in? What does "put the graph in" mean? Put it into the dataset? A
 > query can do *what* by also specifying?

s/; a query can do this by also specifying..././

 >
 > "If a query provides more than one FROM clause..." -- sentence is
 > awkward.
 >
 > 8.2.2 Specifying Named Graphs
 >
 > "Each IRI is used to provide one..." -- provide? What does that mean
 > here?
 >
 > Oh, and we get another language-sounding construct hereabouts... the
 > "clause"... How does that related to an operator, keyword, or pattern?
 > Does it not relate? I'm confused.

"clause" is used to indicate a part of the SPARQL language.  The term is also 
used in the grammar itself.  Other suggestions welcome.

 >
 > 8.3 Querying the Dataset
 >
 > "This is by either using an IRI..." -- huh?

"GRAPH can provide an IRI to select one graph or use a variable which will 
range over the IRIs naming graphs."

 >
 > 8.3.1 Accessing Graph Names
 >
 > "The query below matches the graph pattern on each of the named graphs
 > in the dataset..." -- I don't know what "the graph pattern *on each of
 > the named graphs*" means.
 > Sentence is confusing.

I don't know how else to put this given the 'range' text above.

 >
 > 8.3.3 Restricting possible Graph IRIs -- s/Possible/possible/

Done.

 >
 > "A variable used in the GRAPH clause may also be used in another GRAPH
 > clause..." -- and? Does this mean they're the same variable?

Yes.

 >
 > "This can be used to find information..." -- Antecedent of this is...?

Sentence removed.

 >
 > 8.3.4 Named and Default Graphs
 >
 > "The default graph is being used to record the provenance
 > information..." -- Is this normative?

 > Informative? Formal? Informal? Since it's the only example of graph
 > relations used, it will seem endorsed or a best practice. I don't think
 > that's appropriate here.

Added "In this example, .."

 >
 > 9 Solution Sequence and Modifiers
 >
 > "Modifiers are applied in the order given by the list." -- What list?

The one above that sentence.

?? "Modifiers are applied in the order given above."

 > Does this mean modifiers *must*
 > be applied in some order? As written, I don't think it says that.
 >
 > 9.1 ORDER BY
 >
 > The way ORDER BY is described, it sounds like some kind of function.
 > The syntax of ASC and DESC
 > *looks* like function syntax. Why?

DESC/ASC can take a variable, bracketed expression or a function.

bracketed expressions have to be used here for the same reason that FILTER 
takes a bracketed expression or a function to keep the grammar LL(1).

(Coudl argue that DESC() is functional - it reverses the partial ordering)

 > Isn't the relationship between ORDER
 > BY and some variable (?name) the same as the relation between DESC or
 > ASC and some variable? I expected ORDER_BY(?name) DESC(?emp); or ORDER
 > BY ?name DESC ?emp; but not ORDER BY ?name DESC(?emp).
 >
 > 9.3 DISTINCT
 >
 > "The solution sequence can be modified...in the sequence is unique"
 > -- by which standard of identity
 > is this to be determined?

Term distinct.

"... is a unique RDF Term."

 >
 > 9.4 OFFSET
 >
 > "OFFSET causes the solutions generated to start after the specified
 > number of solutions" -- this is really awkwardly worded.
 >
 > In the next sentence, I don't understand what work "initially" is
 > supposed to do.
 > I think there is a better word than "predictable"; perhaps "stable"
 > or "deterministic" or some such.
 > Better to just say that LIMIT/OFFSET should be used with ORDER BY to be
 > useful.

Done.

 >
 > 9.5 LIMIT
 >
 > Another variant for describing syntax: "The LIMIT form..." Is "form"
 > a special term here?

"... LIMIT clause ..."
 >
 > 10 Query Result Forms
 >
 > This is confusing. We originally called these "query forms" and we have
 > "result forms". "Query result forms" is just confusing. I suggest we
 > revert to "Query Forms".

Done.

 >
 > Also, for my $$, this is just in the wrong place and contributes to the
 > sense that there really *is* no real organizational scheme to the
 > "informal" presentation of the language.
 >
 > The query forms section should be at or near the *beginning* of the
 > document's "informal" section.

Good idea - I think we should at least add something to section 2.
Noted an @@ in this editorial pass.

 >
 > FWIW, I've read several blog comments recently to the effect of "I
 > didn't know CONSTRUCT was in SPARQL" -- that it's tacked on at the end
 > can't help by contribute to that fact.

Could you provide links, please?

 >
 > 10.1 Selecting Variables
 >
 > "Results can be thought of as a table or result set..." -- First, this
 > is just really awkward. They can be thought of as lumps of blue cheese
 > floating in the ether. What matters is what they *are*.
 > Second, this is redundant; we've already had a description of the
 > tabular presentation style of result sets in this document.

Removed.

 >
 > 10.2 Constructing an Output Graph
 >
 > "...substituting for the variables into the graph template" -- s/in/
 > into/

Done.

 >
 > Next paragraph: drop the parens; replace the "(" with a comma.

Done.

 >
 > Last sentence in that paragraph is a run-on.

It refers to triples in the template that have no variables; different from 
after substitution.

 >
 > 10.2.2 Accessing Graphs in the RDF Dataset
 >
 > "Using CONSTRUCT it is possible" -- add a comma after CONSTRUCT.

Done

 >
 > And drop the parens, replace w/ commas.

Done

 >
 > 10.2.3 Solution Modifiers and CONSTRUCT
 >
 > "2" should be spelled out, "two".

Done.

 >
 > 10.3 Descriptions of Resources (Non-normative)
 >
 > What's a "Non-normative Resource"? Or, rather, what are "Non- normative
 > Descriptions of Resources"?
 >
 > This is ambiguous in at least two dimensions: is this supposed to
 > indicate that this *section* is not normative? If not, which of the two
 > aforementioned readings is intended?
 >
 > If this section is "non-normative", that means that the entire
 > remainder of the document *is* normative, including all the commentary
 > and design discussion. Or something...
 >
 > Oh, and which part is meant as "non-normative"? 10.3? 10.3.*
 >
 > This really needs to be sorted out *before* LC.
 >
 > "Current conventions for DESCRIBE return an RDF graph without any
 > specified constraints" -- what does that mean? It's completely opaque
 > IMO.
 >
 > "As with any query, a service may refuse to serve a DESCRIBE query"...
 > What's a service? If this is meant to allude to some protocol thing,
 > why not have a link or pointer to that thing? I guess the protocol doc
 > is a "companion", but one that this doc can't talk about? :>
 >
 > What's a "knowledge base"? What's a "target knowledge base"?
 >
 > What's a "SPARQL query processor"? Is that different than the "service"?
 >
 > 10.3.3 Descriptions of Resources
 >
 > The commentary and design discussions should be dropped.
 >
 > How about we just say "DESCRIBE is intentionally unspecified" and leave
 > it at that?
 >
 > Also, I object to CBD being referenced under the rubric of "other
 > possible mechanisms"... Either list others or drop this one. CBD has no
 > special status or interest that I'm aware of. And it's been criticized,
 > so it's not "the thing everyone does".

It was a working group decision to put in an explicit mention (I was not in 
favour).

 >
 > 10.4 Asking "yes or no" questions
 >
 > This section title is awkward. It's not capitalized like any other
 > section head, and it's not clear what a "yes or no" question is...
 >
 > 10.1, 10.2, 10.3, and 10.4 should be titled SELECT, CONSTRUCT,
 > DESCRIBE, and ASK respectively.

Good idea - done.

 >
 > [I'm skipping from 11 to...]
 >
 > B. Conformance

EricP?

 >
 > I don't think this section is sufficient. There's a lot of talk in the
 > doc about error conditions, warnings, and lots of mays and musts --
 > none of that is covered by the grammar or result forms conformance
 > stuff, nor is it covered in the protocol spec. I think this is a
 > problem and will hurt interoperability.
 >
 > "See those specifications for their conformance criteria" -- how about
 > a link?
 > http://www.w3.org/TR/rdf-sparql-protocol/#conformance
 >
 > Finally, the sentence starting "Note that the SPARQL protocol
 > describes" should be struck. Any such commentary or note doesn't belong
 > in the query language spec at all, IMO, and certainly not in the
 > section on conformance. It sticks out like a sore thumb.
 >
 > If there is interest in a statement like this in the protocol spec,
 > that should be handled in the normal process for the WG. In fact, #4 in
 > the protocol conformance section already says that, so this statement
 > is also redundant and further muddies the normative status of the query
 > spec...
 >
 > D. Collected Formal Definitions
 >
 > "The collected formal definitions are collected..."

Removed the appendix.

 >
 > E. Internet Media Type, File Extension and Macintosh File Type
 > (Normative)
 >
 > So *this* is the only normative part of the spec? Oh, except for the
 > Normative References part of F.
 > References. That's...odd.

As per convention, numbered sections are normative unless noted and appendices 
are not, unless noted.  I've noted the normative nature of the grammar.

 >
 >
 >
 > Cheers,
 > Kendall

CVS commit version 1.27


	Thank you for all the comments, they have been a great help,
	Andy

Received on Friday, 2 March 2007 15:37:06 UTC