Re: [RDFa] Response to Reviewer Comments on RDFa Primer

Ben,

I'm happy with the way you handled my comments. As 
far as I'm concerned, please go ahead.

Guus


Ben Adida wrote:
> 
> Hi all,
> 
> I've integrated reviewer comments into the RDFa Primer, snapshot today
> and available at:
> 
> http://www.w3.org/2006/07/SWD/RDFa/primer/20070227/
> 
> Here's a summary of how comments from Guus and Antoine were addressed.
> 
> Guus
> http://lists.w3.org/Archives/Public/public-swd-wg/2007Jan/0056
> 
>> 2. RDFa Primer, 3rd revision
>>
>> Status section should be changed to reflect new 
>> situation (SWD).
> 
> DONE.
> 
>> A "Changes" section is missing, please add.
> 
> DONE.
> 
>> Sec. 2:
>>
>> The iCal and VCard examples would benefit from 
>> some (nonformal,
>> textual) explanation of what they contain.
> 
> DONE:
> 
> "The markup describes an event: a talk that Jo is giving. This event
> starts at 10am on May 8th. A summary of the event is "a talk at XTech
> 2007 on web widgets." We also have contact information for Jo: she works
> for the organization Example.org, with job title of "Distinguished Web
> Engineer." She can be contacted at the email  address "jo@example.org.""
> 
>> [[
>>    Note how the about attribute is inherited down 
>> the DOM tree hierarchy:
>> ]]
>> You assume the reader knows about how the DOM 
>> hierarchy works. Either
>> make this clear in the "Intended audience" section 
>> or mark this as a
>> note for a particular reader subset.
> 
> I've simplified the language:
> "Note how the about attribute is inherited from parent elements in the
> HTML: the about  attribute on the nearest ancestor applies to declared
> structured data."
> 
>> Typo: "Simple enough!,"
> 
> FIXED.
> 
>> Sec. 2.6: suggestion to include a short discussion 
>> about the resulting
>> triple set, e.g. the talk is not linked to Jo Smith.
> 
> The triples now show the full URI, so as to more clearly link to Jo
> Smith without complicating the exposition.
> 
>> Sec. 3:
>>
>> When you introduce resp literal and URI 
>> properties, refer back to
>> Sec. 2 to indicate how this distinction becomes 
>> apparent there.
> 
> Section 2.6 explains this a bit more clearly to prepare the reader.
> 
>> [[
>>    An RDFa-aware browser would thus extract the 
>> following RDF triples:
>> ]]
>>
>> Why didn't you add similar example triples in Sec. 
>> 2? Given what you
>> stated about required knowledge of RDF I would 
>> suggest to explain the "<>"
>> notation.
> 
> The triples are all in section 2.6 (for section 2), so that the reader
> is gently introduced to them. Then, they are inline for Section 3 and
> onwards. I've explained the notation in 2.6.
> 
>> [[
>>    (The ^^XMLLiteral notation, which denotes a 
>> datatype, will be
>>    explained shortly.)
>> ]]
>>
>> XMLLiteral was already used in Sec. 2.6, so move 
>> this remark to 2.6.
> 
> DONE.
> 
>> Sec. 4:
>>
>> About the editorial note: I don't really see the 
>> repetition. I
>> actually like this treatment of "advanced" RDFa 
>> features.
> 
> OK. Section 4 stays, editorial note removed.
> 
>> Sec. 5:
>>
>> Make clear whether this section is a required 
>> read. I would suggest
>> not. Is it correct to say that this section mainly 
>> adds info about how
>> to handle blank nodes? If so, please make this 
>> explicit.
> 
> DONE. Here's the first paragraph of Section 5:
> 
> "
> If the reader wishes only to embed simple, name-value pairs into an HTML
> document, this section is not required reading. However, many structured
> datasets quickly require some additional level of depth. In this
> section, we consider these more complex structures. One popular RDF
> vocabulary is FOAF [FOAF], which provides structure for social
> networking and personal information. FOAF is particularly interesting to
> consider because it provides deeper structure than the examples provided
> so far: a FOAF person has an office, which has an address, which has a
> street, city, zip code, and country. So far, we have only explained how
> to define structure "one-level deep."
> "
> 
> 
> Antoine
> http://lists.w3.org/Archives/Public/public-swd-wg/2007Jan/0059
> 
>> General comment:
>> - In the code examples, it would be really nice to emphasize (bold?) the 
>> RDFa elements (that is, the xhtml tags and attributes) that are 
>> introduced and explained by the current section (property, content, 
>> rel,...), for pedagogical purposes
> 
> NOT DONE YET.
> Yes, completely agreed, but we haven't had time to do this yet. We'll
> work on this before Last Call.
> 
>> Specific comments
>> 2.3
>> "Note how the about attribute is inherited down the DOM tree hierarchy: 
>> the nearest ancestor with a declared about applies to declared 
>> structured data."
>> The end of the sentence is a little bit difficult to understand, I think.
> 
> simplified, as per Guus's comment, too.
> 
>> 3.2
>> On abbreviation (removing the span) [perhaps this is not only editorial!]
>> " The span element is actually not required. One can easily add the RDFa 
>> attributes to existing HTML elements, without adding a span:"
>> -> Isn't it only possible when values of abbreviated triples do not have 
>> the same value? (e.g. same dc:creator and dc:publisher)
> 
> Not quite sure what the confusion is here, but the text has been
> clarified as follows:
> 
> "When the existing HTML elements already delineate the exact structure,
> adding a new span element is not required."
> 
>> 4.1
>> problem of literal and individual-ranged property
>> The value of a dc:creator can be a literal or an individual, therefore 
>> this property can appear as value of both "rel" and "property" 
>> attributes. This seems not problematic but should be acknowledged, not 
>> to make the reader wondering wether this is a bug or a feature.
> 
> DONE:
> 
> "In the above markup and triples, as well as in the rest of the
> document, we slightly abuse the dc:creator  predicate, which is most
> often meant to refer to a person, not just a literal."
> 
>> 4.3
>> "The result of such syntax is an RDF bnode, an advanced topic which we 
>> skip in this Primer."
>> -> and yet it is mentioned in 5.4
> 
> Removed the comment, as the bnode treatment is still in Section 5.
> 
> -Ben
> 

-- 
Vrije Universiteit Amsterdam, Computer Science
De Boelelaan 1081a, 1081 HV Amsterdam, The Netherlands
T: +31 20 598 7739/7718; F: +31 84 712 1446
Home page: http://www.cs.vu.nl/~guus/

Received on Tuesday, 27 February 2007 23:18:50 UTC