Feedback from Bob DuCharme <[email protected]>
authorGavin Carothers <gavin@carothers.name>
Tue, 16 Aug 2011 13:35:44 -0700
changeset 129 ecdff82eb84d
parent 128 b88507de808e
child 132 8d0a8b1bb60c
Feedback from Bob DuCharme <[email protected]>

http://lists.w3.org/Archives/Public/public-rdf-comments/2011Jul/0000.html

Blank node section feedback not complete, whole section has readability issues.

Collection section feedback not complete, ditto.
rdf-turtle/index.html
--- a/rdf-turtle/index.html	Tue Aug 16 11:31:51 2011 -0700
+++ b/rdf-turtle/index.html	Tue Aug 16 13:35:44 2011 -0700
@@ -137,11 +137,11 @@
     <section id='sotd'>
       <p>
 			Turtle is already a reasonably settled serialization of RDF.  Many 
-			implementations of Turtle already exist, we are hoping for feedback from those
+			implementations of Turtle already exist. We are hoping for feedback from those
 			existing implementers and other people deciding that now would be a good time
 			to support Turtle. There are still a few rough edges that need polishing, and 
-			better alignment with the SPARQL triple patterns. The working group does not 
-			expect to make any large changes to the existing syntax.
+			better alignment is needed with the SPARQL triple patterns. The working group 
+			does not expect to make any large changes to the existing syntax.
       </p>
     </section>
 	
@@ -163,17 +163,17 @@
 			<a href="http://www.w3.org/TR/2008/REC-rdf-sparql-query-20080115/">SPARQL Query Language for RDF</a>
 			[[RDF-SPARQL-QUERY]] grammar for <a href="http://www.w3.org/TR/sparql11-query/#rTriplesBlock"><code>TriplesBlock</code></a>. The two grammars share production and terminal names where possible.</p>
 	</section>
-	<section>
+	<section class="informative">
 
 			<h2>An Introduction to Turtle (Informative)</h2>
-			<p>This section is informative.  The
+			<p>The
 			<a href="#sec-syntax">Turtle Syntax</a> and <a href="#sec-grammar">Turtle Grammar</a> sections formally define the language.
 			</p>
 
 			<p>A Turtle document allows writing down an RDF graph in a compact
 			textual form.  It consists of a sequence of directives, triple-generating
-			statements or blank lines.  Comments may be given after a <code>#</code> that is not part of another lexical token
-			and continue to the end of the line.</p>
+			statements and optional blank lines.  Comments may be given after a <code>#</code> 
+			that is not part of another lexical token and continue to the end of the line.</p>
 
 			<p>Simple triples are a sequence of (subject, predicate, object)
 			terms, separated by whitespace and terminated by '.' after each
@@ -218,7 +218,7 @@
 				URI later in the document may use a <em>prefixed name</em> that
 				starts <code>foo:</code> to stand for the longer IRI.  So for
 				example, the prefixed name <code>foo:bar</code> is a shorthand for
-				the IRI <code>http://example.org/ns#bar</code>.</p>
+				the IRI <code>&lt;http://example.org/ns#bar&gt;</code>.</p>
 
 				<pre class="example"><script type="text/turtle"># this is a complete turtle document
 @prefix foo: <http://example.org/ns#> .
@@ -281,10 +281,10 @@
 </script></pre>
 
 
-				<p>Literals <span class="non-issue">, prefixed names</span> and IRIs may also contain escapes to encode surrounding
+				<p>Literals <span class="non-issue">, prefixed names</span> and IRIs may also contain escape sequences to encode surrounding
 				syntax, non-printable characters and to encode Unicode characters by
 				codepoint number (although they may also be given directly, encoded
-				as UTF-8).  The character escapes are:</p>
+				as UTF-8).  The character escape sequences are:</p>
 
 				<ul>
 				<li><code>\t</code> (U+0009, tab)</li>
@@ -303,7 +303,7 @@
 				</li>
 				</ul>
 
-				<p>See the <a href="#sec-strings">String escapes</a> section for full details.</p>
+				<p>See the <a href="#sec-strings">String escape sequences</a> section for full details.</p>
 
 				<p class="issue">
 				  <a href="http://www.w3.org/2011/rdf-wg/track/issues/67">ISSUE 67</a> The inclusion of escape sequences in prefixed names is undecided.
@@ -315,8 +315,8 @@
 
 				<p>The current base IRI may be altered in a Turtle document using the
 				<code>@base</code> directive.  It allows further abbreviation of
-				IRIs but is usually for simplifying the IRIs in the data, where
-				the prefix directives are for vocabularies that describe the data.</p>
+				IRIs but is usually used for simplifying the IRIs in the data, where
+				the prefix directives are used for vocabularies that describe the data.</p>
 
 				<p>Whenever this directive appears, it defines the base IRI for which
 				all relative IRIs are resolved against.  That includes IRIs,
@@ -352,7 +352,8 @@
 				<section id="abbrev">
 				<h3 >Abbreviating common datatypes</h3>
 
-				<p>Decimal integers may be written directly and correspond to
+				<p>Decimal integers may be written without quotation marks or a 
+datatype indicator and correspond to
 				the XML Schema Datatype
 				<a href="http://www.w3.org/TR/xmlschema-2/#integer">xsd:integer</a>
 				in both syntax and datatype IRI.</p>
@@ -403,7 +404,8 @@
 
 				</script></pre>
 
-				<p>Boolean may be written directly as <code>true</code> or
+				<p>Boolean may be written without quotation marks or a 
+datatype indicator as <code>true</code> or
 				<code>false</code> and correspond to the
 				the XML Schema Datatype
 				<a href="http://www.w3.org/TR/xmlschema-2/#boolean">xsd:boolean</a>
@@ -481,7 +483,7 @@
 			the parsing begins with a context-defined In-Scope Base URI. Each <code>@base</code> directive 
 			sets a new In-Scope Base URI, relative to the previous one. <code>@prefix</code> directives 
 			map a local name to an IRI, also resolved against the current In-Scope Base URI. 
-			Subsequent <code>@prefix</code> may re-map the same local name.</p>
+			Subsequent <code>@prefix</code> directives may re-map the same local name.</p>
 
 			<p>Turtle IRI syntax, including relative IRI resolution, is defined by <a href="http://www.w3.org/TR/rdf-sparql-query/#QSynIRI">SPARQL Query section 4.1.1</a> (noting the different spellings of the <code>PREFIX</code> and <code>BASE</code> keywords).</p>
 
@@ -532,20 +534,20 @@
             </p>
           </section>
           <section  id="sec-strings">
-            <h3>String Escapes</h3>
+            <h3>String Escape Sequences</h3>
 
             <p>Turtle strings and IRIs can use <code>\</code>-escape sequences to
             represent Unicode code points.</p>
 
 
-            <p>The following table describes all the escapes
+            <p>The following table describes all the escape sequences
             allowed inside a <a href="#prod-turtle2-String">string</a>
             or <a href="#prod-turtle2-IRI_REF">IRI_REF</a>:</p>
 
             <table>
               <thead>
                 <tr>
-                  <th>Escape</th>
+                  <th>Escape sequence</th>
 
                   <th>Unicode code point</th>
 
@@ -616,7 +618,7 @@
           <section id="sec-grammar-grammar">
           <h3>Grammar</h3>
             <p>The <abbr title="Extended Backus–Naur Form">EBNF</abbr> used here is defined in XML 1.0 (Third Edition)
-            [[!EBNF-NOTATION]]. Production labels consisting of a number and a final 's', e.g. [<a href="http://www.w3.org/TR/2008/REC-rdf-sparql-query-20080115/#rRDFLiteral"><span class="prodNo">60s</span></a>], reference to the production with that number in the <a href="http://www.w3.org/TR/2008/REC-rdf-sparql-query-20080115/#sparqlGrammar">SPARQL Query Language for RDF grammar</a> [[RDF-SPARQL-QUERY]].
+            [[!EBNF-NOTATION]]. Production labels consisting of a number and a final 's', e.g. [<a href="http://www.w3.org/TR/2008/REC-rdf-sparql-query-20080115/#rRDFLiteral"><span class="prodNo">60s</span></a>], reference the production with that number in the <a href="http://www.w3.org/TR/2008/REC-rdf-sparql-query-20080115/#sparqlGrammar">SPARQL Query Language for RDF grammar</a> [[RDF-SPARQL-QUERY]].
             </p>
             <p class="note">There are known formating issues with the table form of the grammar. Please see <a href="turtle.bnf">turtle.bnf</a> for exact grammar.</p>
             <div data-include="turtle-bnf.html">
@@ -684,7 +686,7 @@
                 </tbody>
               </table>
 
-              <p><a id="unescape">¹</a> <a href="http://www.w3.org/TeamSubmission/turtle/#sec-strings">Section 3.3</a> defines an mapping from <code>escaped unicode strings</code> to <code>unicode strings</code>. The following lexical tokens are unescaped to produce <code>unicode strings</code>: <a class="type IRI" href="#term-turtle2-IRI_REF">IRI_REF</a>, <!-- <a class="type PNAME_NS" href="#term-turtle2-PNAME_NS">PNAME_NS</a>, --><!-- <a class="type IRI"          href="#term-turtle2-PNAME_LN">PNAME_LN</a>, --><a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL1">STRING_LITERAL1</a>, <a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL2">STRING_LITERAL2</a>, <a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL_LONG1">STRING_LITERAL_LONG1</a> and <a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL_LONG2">STRING_LITERAL_LONG2</a><!-- and <a class="type langTag"      href="#term-turtle2-LANGTAG">LANGTAG</a> --><!-- and <a class="type bNode"        href="#term-turtle2-BLANK_NODE_LABEL">BLANK_NODE_LABEL</a> -->.</p>
+              <p><a id="unescape">¹</a> <a href="http://www.w3.org/TeamSubmission/turtle/#sec-strings">Section 3.3</a> defines a mapping from <code>escaped unicode strings</code> to <code>unicode strings</code>. The following lexical tokens are unescaped to produce <code>unicode strings</code>: <a class="type IRI" href="#term-turtle2-IRI_REF">IRI_REF</a>, <!-- <a class="type PNAME_NS" href="#term-turtle2-PNAME_NS">PNAME_NS</a>, --><!-- <a class="type IRI"          href="#term-turtle2-PNAME_LN">PNAME_LN</a>, --><a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL1">STRING_LITERAL1</a>, <a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL2">STRING_LITERAL2</a>, <a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL_LONG1">STRING_LITERAL_LONG1</a> and <a class="type lexicalForm"  href="#term-turtle2-STRING_LITERAL_LONG2">STRING_LITERAL_LONG2</a><!-- and <a class="type langTag"      href="#term-turtle2-LANGTAG">LANGTAG</a> --><!-- and <a class="type bNode"        href="#term-turtle2-BLANK_NODE_LABEL">BLANK_NODE_LABEL</a> -->.</p>
           </section>
           <section id="sec-parsing-triples">
           <h3>RDF Triples Constructors</h3>