- From: Seaborne, Andy <andy.seaborne@hp.com>
- Date: Thu, 01 Mar 2007 15:27:44 +0000
- To: dawg mailing list <public-rdf-dawg@w3.org>
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