[RDFa] Response to Reviewer Comments on RDFa Primer

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

Received on Tuesday, 27 February 2007 16:04:40 UTC