Re: SPARQL / Language spec ready for review [Howard's feedback]

I said I'd get to this today.
I was wrong; had to play with the health inspections and immigration
servivces all day. I only just finished Daves and Howards will take
more attention than I have remaining. Should be back on in 8-10 hours.

On Tue, Oct 05, 2004 at 07:12:27AM -0700, Howard Katz wrote:
> 
> Hi Eric,
> 
> This is done off a fairly quick read. I haven't tried to correlate my
> feedback against Dave's or anyone else's comments. I'm mostly *not* doing a
> lot of nit-picking against spelling errors and other typos at this point,
> ie, this is a bit of a higher-level view. This was reviewed against 1.82.
> 
> Hope it's useful,
> Howard
> 
> ------------------------
> 1 Introduction
> 
> If you're having sub-headings, as in "Document Outline" and "Document
> Conventions", wouldn't it be more consistent to sub-number them, as in "1.1"
> and "1.2"?
> 
> ---------------------
> 2 Making Simple Queries
> 
> Why not use the same data and query example(s) in the initial pictorial
> section and the following SPARQL syntax section? That way readers would get
> a better feel for how one form translates into the other.
> 
> -----------------------
> last paragraph
> 
> Where doesn't the "andy" come from? I don't see him in the graph above.
> 
> ------------------------
> 2.1 Writing a Simple Query
> 
> Second paragraph, "The terms quoted ..."
> 
> It's a fair distance from this sentence to the actual example below, and the
> reader's eyes have to jump down to the example and then find their way all
> the way back up again. Why not move this paragraph to either after the
> "Data:" section or after the "Query:" section?
> 
> ----------------------
> 2.2 Triple Patterns
> 
> I'm not sure if this requires a bit of reorg or not, but all the examples in
> the preceding section have WHERE clauses containing triple patterns, but you
> don't introduce the concept until here.
> 
> More importantly, you never say what a triple pattern IS (ie, something
> along the lines of "A template for describing an s-p-o triple, with
> variables representing missing information to be filled in by the query" or
> some such. That would be very useful for reader.
> 
> At a minimum, I'd change sentence one from
> "The building blocks of queries are triple patterns"
> to
> "The building blocks of queries are triple patterns, shown as the arguments
> of the WHERE clauses in the three queries in the preceding section."
> 
> ---------------------
> As well, a brief sentence explaining that triple patterns are delimited by
> parentheses ("(" and ")") would be useful.
> 
> --------------------
> Paragraph 2, "A triple pattern has either a graph label (URIRef, literal) or
> a named variable in each of the subject, predicate and object positions."
> Literals of course can only go in the object position. Is it ok to be this
> imprecise? (I'm asking because I don't know and don't have a strong
> opinion.)
> 
> ----------------------
> Definition: Triple Pattern
>       "3" -> "three"
> 
> ----------------------
> 2.3 Graph Patterns
> First paragraph, "This starts with conjunction - the 'and' of triple
> patterns."
> 
> It's not clear what "This ..." refers to. How about something like, "We'll
> first look at conjunctions, which combine triple patterns using "and".
> 
> -----------------------
> Paragraph starting "There are is a bNode ..."
> 
> 1) "are is" -> "is"
> 
> 2) I don't understand the final clause in second sentence: ", nor to any
> query."
> 
> ------------------------
> 2.4 Multiple Matches
> 
> "The results of query" -> "The results of a query"
> 
> ------------------------
> 4.2 Multiple Optional Blocks
> 
> Second paragraph, you introduce the concept of outer block. This hasn't been
> previously discussed, so it's unclear what this refers to. Please define. As
> well, you follow with a hypothetical, "If a new variable is introduced in an
> optional block ...", a short "WHERE" snippet example showing this would be
> very helpful.
> 
> ------------------------
> 4.3 Optional Matching
> 
> Is there a new syntactic feature introduced here? If so, an example would be
> helpful.
> ------------------------
> 5 Nested Patterns
> 
> It would be useful to introduce this section with a brief explanation of
> what nesting is. Ie, What is its purpose? Why is it useful?
> 
> ------------------------
> Final example in section:
> 
> I don't see a correspondance between the arguments of the SELECT statement
> and the headings in the result table. "mbox" would have to be SELECTed to be
> output, wouldn't it, and what happened to "name"?
> 
> ------------------------
> 8 Choosing What to Query
> 
> Third paragraph, "To execute a query, there needs to be the query and an RDF
> graph."
> Awkward. How about: "Query execution requires both a query and an RDF
> graph."
> 
> -------------------------
> 9 Querying the Origin of Statements
> 
> I realize you have a footnote on the first sentence saying the semantics are
> undefined, but how about at least a very loose explanation of what a SOURCE
> is in the paragraph itself, so the reader at least has a rough idea of
> you're talking about? Maybe the footnote could be reworked and moved into
> sentence number two? Ie, something like (I'm not claiming this is
> technically accurate):
> 
> " ... many RDF data stores augment this with the source of each statement.
> Source is at present undefined, but is expected to refer in some
> implementation-dependent way to the document of origin, possibly given by a
> URL."
> 
> or some such.
> 
> ------------------------
> 10 Summary of Query Patterns
> 
> Does the bullet "disjunction" correspond to the "alternatives" mentioned in
> "6 More Pattern Matching - Alternatives"?  I don't know the ultimate
> dispostion of this section but suggest if it stays and is mentioned in this
> list, that the terminology be made consistent.
> 
> ------------------------
> 11.2 Constructing an Output Graph
> 
> I'm confused by the three boxed snippets. #3 is labelled "Example" -- are
> the first two NOT examples as well? What distinguishes #3 from #1 and #2?
> 
> Also, #3 has "PREFIX . . . CONSTRUCT". Are the ellipses part of the syntax??
> 
> --------------------------
> 11.4 Asking "yes" or "no" questions
>    -> 11.4 Asking "Yes" or "No" Questions
> 
> I'd also invert sentence #1 and tighten a bit:
> "In order just to test whether a query pattern has a query solution or not,
> the application can use the ASK form."
>    ->
> "Applications can use the ASK form to test whether a query pattern has a
> solution or not."
> 
> ------------------------------
> 12.1 Standard Operations
> 
> "The SPARQL language provides some of the operations on plain literals, XSD
> integers and XSD floats taken from those in XQuery and XPath Functions and
> Operators <http://www.w3.org/TR/xpath-functions/>."
> 
> A bit awkward. Do you mean:
> 
> "The SPARQL language provides a subset of the operations on plain literals,
> XSD integers and XSD floats defined in XQuery and XPath Functions and
> Operators <http://www.w3.org/TR/xpath-functions/>."
> 
> 

-- 
-eric

office: +81.466.49.1170 W3C, Keio Research Institute at SFC,
                        Shonan Fujisawa Campus, Keio University,
                        5322 Endo, Fujisawa, Kanagawa 252-8520
                        JAPAN
        +1.617.258.5741 NE43-344, MIT, Cambridge, MA 02144 USA
cell:   +1.857.222.5741 (does not work in Asia)

(eric@w3.org)
Feel free to forward this message to any list for any purpose other than
email address distribution.