sparql language editorial comments section 2.1-2.5

editorial comments on SPARQL language editor's draft rev 1.379
http://www.w3.org/2001/sw/DataAccess/rq23/

=======


Section 2.1 first paragraph: "The SELECT clause identifies...". The
SELECT in this sentence should be in a different font.

In the subsection "Query Term Syntax" the notions of PREFIX and BASE 
are introduced. The difference between the two is not sufficiently 
explained. (I would suggest an improvement but to be honest I'm not 
sure I understand the difference myself).

In the subsection "Examples of Query Syntax" an example is given of
three ways to express the same query. The example is not correct: in
the first two queries 'book1' resolves to the full URI
<http://example.org/book/book1>, while in the third (and fourth) it 
resolves to <http://example.org/book/shelf/book1>. Suggestion: to fix, 
change the BASE definition in the third and fourth query to 
<http://example.org/book/> (so without 'shelf' in the path).



In the subsection "Data  description used in the document" first sentence:

  "The data format used in this document is Turtle used to show each
   triple explicitly."

I think this is grammatically incorrect, at least it's unclear what is 
meant exactly. Suggestion to clarify by rewording to:

  "The data format used in this document is Turtle, since this format
   allows showing each triple explcitly." or alternatively "....since
   this format is [relatively] well suited for human readability."

An example Turtle document is presented in this section, using
Turtle's prefix mechanism. Suggestion: point out explicitly in the
text that Turtle uses an '@' in front of the prefix def, but SPARQL
does not.



Section 2.3 is titled "Basic Graph Patterns". However, the section is
actually about triple patterns. Rename to "Triple Patterns".


Section 2.4 is titled "Matching Basic Graph Patterns". Suggest to
rename to "Basic Graph Patterns and Solutions".

The definition of 'Basic Graph Pattern' refers to triple patterns.
Suggestion to link to the definition of triple pattern.



Section 2.5 "Examples of Basic Graph patterns"

First sentence:

  "The SPARQL syntax uses the keyword WHERE to introduce the Query
   Pattern".

Suggestion: link to definition of Query Pattern.

Despite the title the section only contains one example of a basic
graph pattern. The text immediately launches into an explanation of
blank nodes which confuses the issue, since that is not what the
section is supposed to be about. Suggestion: use a simpler example and
focus exclusively on the issue at hand, namely graph patterns. Replace
explanation of the role of blank nodes with a pointer to section 2.7.
Further suggestion: include more than one example.

Jeen
-- 
Jeen Broekstra          Aduna BV
Knowledge Engineer      Julianaplein 14b, 3817 CS Amersfoort
http://aduna.biz        The Netherlands
tel. +31 33 46599877

Received on Thursday, 9 June 2005 12:37:09 UTC