Re: rq25 (1.18) review (part II)

Addressing editorial comments in this pass up from start sec 5 to end section 7.

Kendall Clark wrote:
 >
 > 5 Graph Patterns
 >
 > "SPARQL is based around graph pattern matching." -- this is the 3rd or
 > 4th similar sentence, spread across the doc, and each one is *slightly*
 > different. Is there some significance to the differences?
 > Is it really necessary to keep repeating the point? I think that
 > confuses spec readers. It confuses me, anyway.
 >
 > 5.1 Basic Graph Patterns
 >
 > "SPARQL pattern matching is defined in terms matching basic graph
 > patterns..." -- "of" missing? Also, what kind of "SPARQL pattern
 > matching"? Triple? Graph? And where is this defined precisely? Can we
 > get a link? A pointer or reference?
 >
 > "Filters can be mixed into...but do not cause the end of a basic graph
 > pattern." -- what is the "end"
 > of a basic graph pattern?
 >
 > 5.1.1 Blank Node Labels
 >
 > s/"Labels"/"labels"/

This is a heading.  Left as "L"

 >
 > This section refers to a "syntax error" -- which one? How's it spelled?
 > Is this a generic syntax error or a specific one? Confusing.

Errors are in the protocol so I've changed the text to be just "A label can be 
used in only a single basic graph pattern in any query."

 > 5.1.2 Extending Basic Graph Pattern Matching
 >
 > "SPARQL is defined for matching RDF graphs with simple entailment."
 > -- this is ambiguous: "simple
 > entailment" is part of the mechanism of matching? Or matching works in
 > the presence of simple entailment? Something else?
 >
 > If this is all that's intended to be said in this section, strike it!

It will say that this can be extended and link to the extension conditions.

 > 5.2 Group Graph Patterns
 >
 > "In a SPARQL query string..." -- what's this? I think it's the first
 > use of this wording. It's different than other wordings, so I'm left to
 > do the boring, tedious interpretive work of trying to decide if it's a
 > new construct or "informal" language. Can't we just stick to the same
 > terms?

Are you suggesting using "SPARQL query" at this point?

 > I see in the Grammar section there is a "SPARQL query string" and a
 > "SPARQL Query String" -- are these the same? If so, are they the same
 > as the "SPARQL Query String" in 5.2?
 >
 > Can't we get some hyperlinks or pointers?
 >
 > Third sentence: run-on.
 >
 > 5.4 Examples
 >
 > Another hyphen/dash problem.
 >
 > "...the filter does not break the basic graph pattern into two pieces"
 > -- huh? Pieces of what?

"... into two basic graph patterns."

 >
 > 5.5 Scope of Filters
 >
 > "A constraint, expressed by the syntax keyword FILTER, is a restriction
 > on solution over the while group in which the filter appears" -- I
 > assume this is supposed to be "...a restriction on a solution over the
 > whole group...". "syntax keyword FILTER" is awkward. I don't remember
 > "keyword" being defined in this doc. I can't find a list of reserved
 > words.

s/syntax //

FILTER is a keyword in the grammar.  Ideally, I'd like to include a list of 
keywords but they are available by a scan of the grammar.

 >
 > 6 Including Optional Values
 >
 > Strike the first sentence; we don't need commentary in the spec on why
 > some feature of the language is useful. That's the point of referring
 > to UC&R at the outset.
 >
 > Much of this paragraph is commentary and should be struck.

I prefer to set the scene here, based on other feedback over the various 
publications the WG has done.  We're writing for several audiences.

 >
 > 6.1 Optional Pattern Matching
 >
 > Semicolon in sentence that starts "In an optional match,..." should be
 > a comma.

Done.

 >
 > "It is unbound" -- what is? Pronouns starting sentences in specs are
 > almost always a "code smell".
 > They create the possibility of ambiguity and are best avoided. Which is
 > easy to do if you've defined a bunch of terms formally.

Removed.

 >
 > 6.4 Nested Optional Graph Patterns
 >
 > "The outer optional graph pattern must match for any nested optional
 > pattern to be matched." -- which one? The outer*most* must match? The
 > nearest outer must match? All outers must match?

Hmm - worse than that, it's all a bit different nowadays.

I propose we delete this (6.4) section.

 >
 > 7 Matching Alternatives
 >
 > "The UNION keyword is the syntax for pattern alternatives." -- I find
 > all such constructions (and there several of them) to be awkward.
 > Better: "Pattern alternatives are created with UNION" or some such.

I think it's worth distinguishing between the syntax and the abstraction of a 
  query.  Being the syntax for something and bing that thing are different. 
Keywords are syntax and don't partake of the abstract concept formed.

 > Saying "keyword" after every keyword is not as good as having a list of
 > keywords. And the typographic change indicates that it's keyword
 > anyway, or would if there were a guide to typographic conventions
 > employed in the spec -- another best practice we seem to have
 > jettisoned.
 >
 > "If the application wishes to know how exactly the information was
 > recorded..." -- this is awkward.
 > Better: "To determine exactly how the information was recorded..."

Done, and rewording later on.

 >
 > "The UNION operator..." -- it's an operator and a keyword? Typography
 > suggest yes. I don't see UNION in the list of operators... Confusing,
 > especially since it's also called a "pattern" nearby. So that's UNION
 > keyword, pattern, and operator. None of which is defined precisely in
 > context, nor linked to a precise definition.

"UNION pattern"

 >
 > "Query results of GP1 UNION GP2..." -- what are GP1 and GP2?

Old text - deleted.

...
 >
 > Cheers,
 > Kendall

Received on Thursday, 1 March 2007 15:27:58 UTC