comments on 2011-07-16 Editors Draft of Turtle spec

The document shows great progress so far, and I look forward to it 
becoming a Recommendation.

I moved a copy of this to my ereader yesterday, and today I see that the 
2011-07-16 draft has already addressed some of the issues I found. 
Automated steps for document quality control such as spell checking 
("compatable"?) and link checking (two bad links noted below) should be 
done before you encourage the public to review the draft. (I reviewed it 
after encouragement from Gavin.)

I was going to split off picky copyediting comments from more 
substantial ones, but some comments fall in between because certain 
unclear parts of the spec may be unclear of grammatical errors, so these 
are listed roughly in order of their appearance in the document.

Bob DuCharme
snee.com/bobdc.blog
@bobdc

------------------------------------

Suggested changes written as s/existing text/proposed new text/

- s/already exist, we are hoping/already exist. We are hoping/ (comma 
splice)

- "and better alignment" needs a verb, e.g. "and better alignment is needed"

- s/writing down/recording of/

- s/or blank lines/and optional blank lines/

- s/declaring a short/declaring of a short/

- following is a bad link:

     optional <a 
href="../rdf-concepts/index.html#dfn-language-identifier">language 
tag</a> or

- meaning of this is unclear: "This is useful for many RDF vocabularies 
that are all defined with a common namespace like IRI."

- s/for the IRI http://example.org/ns#bar/for the IRI 
<http://example.org/ns#bar>/

s/ appending the simple literal with @ and the language tag/appending @ 
and the language tag to the simple literal/

- I didn't understand this: "to provide a blank node either from the 
given BLANK_NODE_LABEL." The next sentence ("A generated blank node may 
also...") is also very confusing.

- "may contain escapes" I haven't noticed many such uses of "escape" as 
a noun this way before. Wouldn't "escape sequences" be better? (Several 
places.)

- s/but is usually for simplifying/but is usually used for simplifying/ 
(and in same sentence) s/are for vocabularies/are used for vocabularies/

- In section 2.3, instead of "written directly" throughout, I think it 
would be more precise to say "written without quotation marks or a 
datatype indicator."

- section 2.5 "provides a blank node" only makes sense to people who 
already know what () means with collections in Turtle. To someone who is 
new to this, it would be very difficult to understand what "provides a 
blank node" means--provides it where?  This could use some additional 
explanation. (In other words, instead of being four short sentences, 
section 2.5 would be better off as six or seven sentences.)

- "See section Collections for the details on the long form of the 
generated triples." There is no such section, and while the term 
collection is defined as part of the grammar in section 4.4, it would be 
useful to include a more informal definition or example of what the spec 
means by this term (which it uses a lot) the first time that it is used, 
or at least a pointer to 
http://www.w3.org/TR/2004/REC-rdf-mt-20040210/#collections.

- s/subsequent @prefix may re-map/subsequent @prefix directives may re-map/

- (section 4.4) s/reference to the/reference the/  (I'm assuming that 
"Production labels" is the subject of this sentence and "reference" is 
the verb; if I'm wrong, the sentence still needs some rework.)

- "unicode" is often spelled with a lower-case "u"

- s/defines an mapping/defines a mapping/

- "Each object N in the document produces an RDF triple: curSubject 
curPredicate N ." I found this sentence very confusing at first--how can 
an object produce a triple? I eventually figured out that it's referring 
to parse-time behavior, so perhaps it would be clearer if the sentence 
began "Upon being parsed, each object N..." I realize that this is in 
the parsing section of the document, but still, these three extra words 
would make the sentence easier to understand.


Again, great work...

Received on Saturday, 16 July 2011 15:04:55 UTC