Re: Primer draft review - syntax section

Dave--

Thanks for the comments.  I'll be working my way through them 
(hopefully) shortly (including borrowing linking ideas from the Syntax 
doc, which you'll notice I've done before!).  A few specific responses 
right now:

Dave Beckett wrote:

> Primer draft
> http://www.w3.org/2001/09/rdfprimer/rdf-primer-20021031.html
> 
> (also reading Brian's comments at
> http://lists.w3.org/Archives/Public/w3c-rdfcore-wg/2002Nov/att-0120/01-rdf-primer-20021031.html
> )
> 
> Sec 1
> 
> +1 to Brian's suggestion of an RDF graph here.


I'm doing it.  I've just got to rewrite the text....


> 
> Sec 2
> 
> +1 on Brian's comments to de-emphasising N-Triples a little.  Just
> describe it as a simple triples syntax.
> 
> s/untyped literals/plain literals/ since that's what Concepts and
> Syntax WD use now.
> 
> Add some links to the Concepts sections/definitions for RDF URI
> References, Literals, Typed Literals, RDF Graphs, Nodes, Triples,
> ... maybe?


Yeah.  Thanks for the examples in the Syntax doc.


> 
> 
> Sec 3 An XML Syntax for RDF
> 
> Maybe stick the example in an attached RDF/XML file, link to it, so
> it can be machine checked?
> 
> "rdf:RDF start-tag" => more correctly, this is called the XML
> document element or root element.  So the sentence could be changed
> to:
> 
>   [[Following the rdf:RDF on this same line is an XML namespace
>   declaration, represented as an xmlns attribute on the rdf:RDF
>   document element.]]


Well, actually the "element" is the whole thing, including the 
start-tag, the contents, and the end-tag.  I think in this case I really 
do mean the start-tag.


> 
> "... prefixed with rdf: are part of the namespace identified by ..."
> 
> maybe refer to the RDF Namespace and point to it:
> "... prefixed with rdf: are part of the [RDF Namespace] identified by ..."
> linking to http://www.w3.org/TR/rdf-syntax-grammar/#section-Namespace
> 
> 
> Consistency;  the exterms:creation-date in the triple representation
> turns into ex:creation-date.  I'd suggest using the same prefix.
> 
> 
> Line 3 para
>   More s/start-tag/document element/
> 
> Line 4-6 para
>   "is to say it's a" => "is to say its a" ?
>     (I'm rubbish at apostrophies, check this)
> 
>   "This is exactly the RDF/XML represents the statement. "
>    =>
>   "This is how RDF/XML represents the statement. "
> 
>   "that we're starting a description, "
>   =>
>   "that we're starting a description of a resource", 
> 
>  " to hold the value "
>  =>
>  " to hold the string literal value "
> 
>  "It is nested within the preceding rdf:Description element,
>  indicating that this property applies to the resource specified in
>  the containing rdf:Description element."
>  =>
>  "It is nested within the containing rdf:Description element,
>  indicating that this property applies to the resource specified in
>  the rdf:about attribute of the rdf:Description element."
> 
>  "The complete URIref of the creation-date property corresponding to
>  the QName <ex:creation-date> would be obtained by replacing the ex:
>  prefix by the namespace URI defined for it in Line 3"
>  =>
>  "The URIref of the creation-date property corresponding to
>  the QName <ex:creation-date> is obtained by appending the
>  name creation-date to the URI of the ex: prefix
>  http://www.example.org/terms/ giving
>  http://www.example.org/terms/creation-date"
> 
> 
> para "In this case, in Line 8 ..."
> 
>  "Because the URIref is being used as an attribute value, we cannot
>  abbreviate it as a QName, as we've done in writing element and
>  attribute names (this is due to the need to conform to XML
>  syntax). Instead, we must write it out as a full URIref."
> 
> not quite right; since XML doesn't require that.  It is up to
> individual XML formats to decide if attribute values take qnames
> or URIs.
> 
> I'd either delete this sentence or say RDF/XML requires it.
> 
> para 
>   It is important to understand that the RDF/XML in the above two
>   examples are abbreviations. The RDF/XML below, in which all
>   resources are represented with separate rdf:Description elements,
>   and each statement is written separately, describes exactly the
>   same RDF graph: 
> 
> is crying out for links!  "above two examples", "rdf/xml below" and
> "same graph"
> 
> I'm wondering if you need to introduce the idea of abbreviations or
> alternate ways to write RDF/XML earlier on?
> 
> 
>   "All blank nodes are assigned arbitrary URIs or blank node identifiers."
> 
> No.
> 
>   "All blank nodes are given blank node identifiers."
> 
> They are not given arbitrary URI(refs)
> 
>   "Each resource is listed in turn as the subject of an un-nested
>   rdf:Description element, using an rdf:about attribute.
> 
> unless they are blank, in which case rdf:nodeID must be used.
> 
>   " For each triple with this resource as subject, an appropriate
>   property element is created, with either literal content (possibly
>   empty) or an rdf:resource attribute specifying the object of the
>   triple."
> 
> unless the object node is blank in which case rdf:nodeID is used on
> the property element.
> 
> I don't define such a basic serialization syntax in the current
> syntax WD, I should think about doing this.


I thought about this myself.  It's true there isn't something called 
"basic serialization syntax";  on the other hand, I think it's probably 
good advice to describe the simplification as something people might use 
for RDF/XML targeted for machine processing.  What do you think about 
just describing this as a suggestion for a simple serialization, or 
something like that?


> 
> sec 3.2
> 
> I'd avoid the defining word in the title
> 
> This is always description, the rdf:ID stuff is shorthand for
> URI-refs that are close to the document URI (or base URI, xml:base
> and so on)


Right.  What you are typically trying to do here, I think, is introduce 
(or indicate) some URIrefs that you intend for people to use to name the 
associated resources.


> 
> You might want to introduce base URI explicitly rather than after
> describing the example.  (I note that relative, base URIs stuff is
> hard to explain clearly.)
> 
> ...
> 
>   "The example also illustrates the fact that the RDF describing a
>   particular resource does not need to be located all in one place;
>   instead, it may be distributed throughout the web."
> 
> I'd avoid "the fact" in my personal style.  Just s/the fact that the/that/
> 
> sec 3.3
> 
>   "One of the abbreviations allowed by RDF/XML is that when properties
>   are not repeated within an rdf:Description element,"
>    ... property elements are not ...
> 
> PLUS the values must be literal strings with the same language (xml:lang)
> 
> And that ignores rdf:type which can be also be moved, only if it
> points at a node with URI-ref.
> 
> 
> The example of parseType="Literal" has typos, bad XML. Plus I changed
> the internal content to use a:Box so as not to confuse with the
> parseType "Collection".  Correct to:
> 
> ----------------------------------------------------------------------
> 1.  <?xml version="1.0"?>
> 2.  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
> 3.              xmlns:ex="http://example.org/stuff/1.0/">
> 
> 5.     <rdf:Description rdf:about="http://example.org/item01">
> 6.       <ex:prop rdf:parseType="Literal"
> 7.             xmlns:a="http://example.org/a#><a:Box required="true">
> 8.             <a:widget size="10" />
> 9.             <a:grommit id="23" />
> 10.          </a:Box></ex:prop>
> 11.    </rdf:Description>
> 
> 12. </rdf:RDF>
> ----------------------------------------------------------------------
> (or check with syntax wd example when it appears)
> 
> 
> I'm wondering if this example needs to be here at all.  Maybe this
> stuff is something we shouldn't include.


Could be.  I'm not clear myself as to which of these things people feel 
are essential for the Primer (partially due to the fact that I hear "foo 
is overkill" from some folks, and "you don't cover bar" from others!).


> 
> --
> 
> skipping to 4.3.3
> 
> Is this something we are keeping?
> 
> A bit of duplication with (current draft)
> http://ilrt.org/discovery/2001/07/rdf-syntax-grammar/#section-rdf-in-HTML
> although this section covers motivations.


No, we're not keeping 4.3.3.


> 
> 6.4
> 
> There is a lot of text here, who owns this?


I do now.  I know there's a lot of text.  What do you suggest (and where)?


> 
> 6.5
> 
> the RDF/XML here could do with a bit of indenting for readability
> 
> 
> END OF REVIEW
> 
> 
> General:
> 
> Add figure numbers for the examples you are using with line numbers
> so that way you can say when you add stuff, you can compare to
> previous versions.  Such as when you do things in the example after
> fig 11 (see, I can't point at it with a link!) you can compare with
> the example, a few paragraphs back.
>   "Compared with the previous two examples, " <= links :)
> 
> Link to various things defined in RDF concepts:
>   Node, Triple, RDF Graph, RDF URI Reference, Literal,
>   Plain Literal, Typed Literal, Blank Node, Blank Node Identifier


All good ideas;  I might ask you some "how to" questions when I actually 
start doing this.


> 
> Rename the WDs:
>   RDF Schema => RDF Vocabulary ... 1.0: RDF Schema (shorthand, RDF Vocabulary)
>   RDF Model Theory => RDF Semantics ...
>   RDF Concepts and Abstract Data Model => RDF Concepts and Abstract Syntax
> etc. and remember to update the references.


In progress


> 
> You might want to cite the exact abbreviations used pointing to the
> newest syntax WD, there should be sections for them all.
> 
> Some of these values like "very" and "easier" are pretty subjective;
> you might want to just place them as alternatives or say "may be easier"
> etc.

> 
> I'm wondering also if we'd rather omit some of these abbreviations in
> the Primer to discourage their use.  I'd vote for ignoring 1)
> property attributes and 2) property attributes on an empty property
> element.
> 


I'd be happy with this, but I'd like to hear from others too.


> 
> I see no show stoppers not already covered by Brian.
> 
> Dave
> 
> 

Thanks again.

--Frank
-- 
Frank Manola                   The MITRE Corporation
202 Burlington Road, MS A345   Bedford, MA 01730-1420
mailto:fmanola@mitre.org       voice: 781-271-8147   FAX: 781-271-875

Received on Wednesday, 6 November 2002 11:26:34 UTC