Re: Review of Turtle doc (part 2)

On Mon, Apr 9, 2012 at 9:08 AM, Andy Seaborne
<andy.seaborne@epimorphics.com> wrote:
> == Meta-comment
>
> What's the process for comments processing?  I'm hoping for acknowledge (or
> refusal, with reason) of each point as has been done elsewhere previously.

Sounds good. Some from the last email have been integrated into the
draft already.

>
> == Summary
>
> As this is last call, and a change that would cause a change in a
> implementation of the LC doc would require a new LC, it's safer to get this
> doc sorted and aim for a single last call.
>
> The grammar is not quite up-to-date.
>
> The process of turning bytes into triples has some missing parts.
>
> There are mistakes around charset between description and registration that
> need sorting out (a change here would be a new LC).
>
> I think a registration of "application/n-triples" is likely to cause less
> confusion over time.
>
> == 6.1 Parser State
>
> "a state of four items"
> There are five items in the bulleted list.
>
> "test:" -- what's this?  occurs three times.
>
> "is bound to the subject production"
> I know what this intends to say, but the wording does not convey it. What
> does "bound" mean in this context?  needs explaining.
>
> The state variables curSubject and curPredicate must be stacks for recursive
> use. e.g. nested blankNodePropertyLists.
>
> == 6.2 RDF Term constructors
>
> Foot note 1 : "section 3.3. defines" -- section 3.3 does not exist.
>
> (the link is actually to 'TeamSubmission/turtle/#sec-strings')
>
> ANON "A blank node" -> "A fresh blank node"
>
> blankNodePropertyList - ditto
> collection -- ditto
>
> In addition,
>
> == 6.3. RDF Triples Constructors
>
> A more formal presentation, for example, written in pseudo code, would be
> clearer.
>
> "novel" blank node -> "fresh" blank node for consistency.
>
> "The node produced by matching blankNodePropertyList is blank node B"
>  where is B mentioned again?
>
> For collections, same about "Bhead".
>
> There is nothing about ";" and ",".

Huh, I thought there was... I wonder if that part got lost in the
shuffle at some point. Will add.

>
> == 6.4 Parsing Example.
>
> Should not mention LALR(1) -- it should be following the description in the
> previous sections of section 6.
>
> There are details in the process that are not in the earlier normative
> description (e.g. ";").
>
> "save curSubject" is in fact a stack.
>
> == 7 Examples
>
> Please give complete examples including prefixes.

Ah, there are still some examples that are not valid Turtle. All
examples should be valid Turtle.

No more <script type="text/plain"> only full Turtle documents.

>
> What's the relationship of this to section 6.4?
>
> What about giving the N-triples forms? (here or later)

Part of the larger question of does N-Triples live in it's own
section, which the WG took a decision last week that it should.

>
> == 8 Identifiers for Turtle
>
> What about N-triples?

N-Triples own section.

>
> Remove "issue".
>
> ttl:turtle ==> http://www.w3.org/ns/formats/Turtleturtle

Removing all talk of Namespace and defining a QName for Turtle per WG decision.

>
> which is not a helpful example.
>
> == 9 Conformance.
>
> The test suites are not correctly licensed.
>
> Add notes that the test suite hasn't been approved yet.
>
> Test 29 is wrong as has been noted. (illegal IRI: a parser can reject the
> file at parse time withotu generating triples).
>
> What's the status of the test suite?  Are there tests for new features like
> escaping?

I don't know that's what I volunteered to do a year ago clean up and
write new tests... ended up editor, oops.

>
> == 10 Media Type
>
> Suggest add example "text/turtle;charset=utf-8" to explain implications of
> charset.
>
> "until such time as the text/ media type tree permits UTF-8"
> This reads like an assertion that it will change at some time but it's
> outside this WG.  Remove.

Agreed.

>
> The registration lists charset as optional.

Not sure if we change the registration here what we need to do with the IANA.

>
> == 11. Turtle in HTML
>
> Is section this formative or informative?
>
> All of section 11 seems to be informative.

Yep, will mark as such.

>
> == 12 N-triples
>
> "The syntax is an improved version"
> ==>
> "The syntax is an revised version"

Yes.

>
> "as a dump format for RDF data."
> ==>
> "as an exchange format for RDF data."
>
> which avoids database language.

Agreed.

Do we wish to reuse the intended for machines language from the top of
the introduction as well?

>
>
> == 12.1 Media Type and Content Encoding
>
> Why is is "application/ntriples" and not "application/n-triples" given the
> language is called "N-triples"?  It would avoid confusion to make it
> "n-triples".

Mostly that -'s in media types tend to be used to denote sections of a
name. Eg: audio/x-ms-wma, application/x-*, application/font-woff etc.
Not sure if it's more or less confusing to match the name or the
convention.

>
> "The content encoding of N-Triples is always UTF-8."
>  Not true - if its "text/plain" then it's ASCII.

Not exactly. N-Triples is content served with application/ntriples. It
is not conforming to serve N-Triples as text/plain, but of course you
can, it's just text in that case and a parser is welcome to try and
interpret text as N-Triples. N-Triples only exists as
application/ntriples.

>
> "As N-Triples is a subset of Turtle it may also be provided as text/turtle.
> "
>  please remove.
> If using "text/turtle;charset=utf-8" then it's Turtle, not N-triples.

Yeah, agreed. Same as above with text/plain ;)

>
> Maybe less formal:  "note that when parsed by a Turtle parser, data in the
> N-Triples format will produce exactly the same triples as the restricted
> N-triples language".

Sounds good.

>
> == 12.3
>
> needed?

Unclear. Was requested to add but there were also objections to adding
it. WG decision needed?

>
> == 12.4
>
> Make the same style as Turtle.

Eric! More yacker HTML output please ;)

>
> Use full names, not "subj", "pred" etc.

Good point.

>
> remove @terminals

Needed for Yacker shouldn't be in output.

>
> Numbering.

Standing question, number with sparql/turtle productions or it's own set.

>
> BLANK_NODE_LABEL is not PN_LOCAL from Turtle anymore.
> PN_CHARS_U
> PN_CHARS are also not from Turtle anymore.
>
> Use of "\\" when "\" is meant.

more Yacker :\

>
> Remove @pass.

Yep and Yacker again.

>
> == Section 13
>
> Not reviewed.
>
> == Section A (Turtle Media Type)
>
> Puts charset under "optional" - isn't it required?
>
> Change control: needs updating.
>
> == Section B (N-Triples media type)
>
> charset not mentioned under parameters.

Correct, N-Triples is UTF-8 only and in the application/ space so does
not need a charset param for UTF-8.

>
>
>
>

Received on Monday, 9 April 2012 16:35:08 UTC