General Document Comments

DAWG members,

I have several comments about the current live version of the SPARQL
specification, in terms of the actual document presentation.  I have a
couple of impressions that I gained while attempting an implementation that
I thought I'd share first.  I perhaps have the uncommon distinction amongst
readers of having not been terribly familiar with XQuery, XMLSchema or other
dependent specs, so a lot of the format and content was new to me.

First, the type system is fairly confusing, mainly in the area of
distinction between typed and untyped literals.  I was able to glaze over
the distinction until I got to the the cast constructor section, where
rdfs:Literal seems to mean untyped literal and typed literals are of their
datatype.  I think that needs to be highlighted there, because it introduced
a mental paradox for me, why literals were different from their datatypes.
The transition between talking about literals as HAVING datatypes and then
BEING that datatype was a little confusing, especially for readers
interested in a practical use of the language, where everything in RDF and
the grammar is technically either a blank node, IRI, or literal.
There is also a lack of discussion on language tags, besides in matching.  I
assumed that's because they're in some other document, but in particular I
found that a mention of whether a literal with a language tag is an untyped
literal or an implicit xsd:string would have been useful for later
reference.

Some of the logical layout of the document is a little confusing.  A couple
of examples:
*	Grouping - There is an entire section on Working with RDF literals (3),
which is half about value constraints.  Value constraints logically have
very little to do with the definition of literals and how they are used
(they technically have just as much to do with IRIs, for instance).  In
addition, literals were already discussed, if as not in as much detail, in
2.1.  And while I'm at it, the two sections in 2.1 called "... used in this
document" should probably be under 1.1 Document Conventions, because they
are document conventions.
*	Balance - There are several sections on fairly minor points, like
"Multiple Matches" (2.6), and yet section 10.1 covers projection and at
least three whole language constructs.  I found myself today wanting to
reference a section on value ordering and having to reference 10.1, which
isn't nearly the granularity I wanted.  Balance is also important for using
the TOC as a navigation feature, which I imagine most users do.
*	Titles - Along with the last point I wanted to add that while it's nice
for a title to be an abstraction of the underlying grammar construct, it's
helpful if somewhere in the title of the section is the construct name.  For
instance, ORDER, LIMIT, OFFSET, OPTIONAL, GRAPH etc. is never mentioned in
any title, yet there is a special point made to capitalize the other
keywords that appear in titles.  If I'm a developer reading this
specification, it would be more efficient if I could easily tell which
section I needed to navigate to.

Oh, and a side note: Section 11.1 uses the r prefix for RDF terms, and then
rdfs is used in the cast constructor section.  Is this purposeful?  If it
is, the r prefix is never associated with an IRI, but I imagined it's
supposed to read rdfs.

I was going to wait and send everything at once, but seeing how fluid the
document is, I thought I'd send my comments prematurely.  I hope I could
provide some value and I apologize in advance for any ignorance in my
reading.

Cheers,
Ryan Levering