Turtle document strategy [Was: Re: Review of Turtle doc (part 1)]

* Andy Seaborne <andy.seaborne@epimorphics.com> [2012-03-30 15:43+0100]
> ACTION-157
> 
> First part of a review of the Turtle document, up to the ened of
> section 5 (the Turtle grammar).
> 
> I'm getting this out now because it covers the structure and
> audience of the document and because it's already a bit long.
> 
> 	Andy
> 
> == General
> 
> 1/ Audience:
> 
> Who is the audience for the document?
> 
>   Data authors?
>   Parser writers?
> 
> The doc, especially in the early sections, feels much more centered
> on parser writers but I'd like to see it being for data authors with
> parser writers material pushed towards the back in a "theory"
> section.

Traditionally, W3C priority is specifications over tutorials. Given
the above choice, I'd say "Parser writers". That said, the intention
was that the text be clear without sacrificing precision.


> 2/ Turtle? N-Triples?
> 
> The document, especially in the earlier sections, talks a lot about
> N-triples, e.g "Introduction" has an N-Triples example but no
> Turtle.

[[
N-Triples triples are a sequence of RDF terms representing the
subject, predicate and object of an RDF Triple. This sequence is
terminated by a '.' and a new line (optional at the end of a
document).

  _:subject1 <http://an.example/predicate1> "object1" .
  _:subject2 <http://an.example/predicate2> "object2" .

N-Triples triples are also Turtle triples, but Turtle includes other
representations of RDF Terms and abbreviations of RDF Triples.
]]

The example is both N-Triples and a simple and expository form of
Turtle, so I'm having a hard time aligning the comment with the text.


> It reads almost like an Turtle/N-Triples comparison at times with
> Turtle assumed background knowledge.
> 
> It would be better to define Turtle, then to discuss N-Triples if
> you want to frame N-triples as a simple subset of Turtle.
> 
> The mixture, and comparing Turtle to N-triples (section 1 and 2), is
> quite confusing.  (Alternative, start with writing down triples,
> then introduce the Turtle syntax forms for better expression. But I
> suggest the "describe Turtle, then N-Triples" approach.)

We can't describe Turtle all in one go so I started with the simple
forms, moving on to the alternate forms of terms and triple
patterns. As it happens, the simple forms are exactly N-Triples so it
made sense to either 1. label them specially to be referenced by a
later N-Triples section, or 2. label them as N-Triples. Trying the
first, the labels were pretty arcane (simple-triple,
non-prefixed-absolute-IRI, datatyped-or-langtagged-literal) so I went
with the second. Do you see a better alternative?
-- 
-ericP

Received on Friday, 30 March 2012 17:54:36 UTC