RE: RDFa Primer WD#2 Ready - Addressing Gary's Comments from WD#1

Hi Ben and everyone in the task force,

I have reviewed the Primer at
http://www.w3.org/2001/sw/BestPractices/HTML/2006-04-24-rdfa-primer

I only have cosmetic suggestions. Congrats, it is good to go from me.
Please consider my suggestions below. 

Cheers,

Gary

--- Comments ---

Generally, the see Section ?? in various places.

Section 2:

  Congratulations for the effort. This is a very clear and well defined
use case to give a quick overview of the method of mark up, as well as
articulating the reason for doing so. It has addressed my previous
concerns on a quick scene-setting overview.

Section 2 and 2.1

  Suggestion: Reread and tidy up English grammar.

Section 2.2

  Comment: Great use case - "...readers of her blog might be able to add
her talk directly to their calendar."

  Suspect missing metadata: No triple for Jo speaking at the event.
There is no triple linking Jo the person to the anonymous "Vevent".

Section 2.3

  Confusion: " Jo then sets up her vCard ... the vCard schema does not
require declaring a vCard type - i.e. there will be no role attribute
this time ..."  --  The causal relationship between the two sentences
isn't at all obvious to the reader. Since the use of "role" was simply
called into existence in 2.2 without any explanation why it was used,
compare to say any other possibilities. Is the difference being that you
don't want the instance of Vevent to be explicitly identifiable
(anonymous)? Otherwise "about" would be a more appropriate thing to use?

  English quibble: "Simple enough!, Jo realizes, as she adds her first
vCard fields: name, title, organization and email."  --  It reads like
this sentence is not finished.

Section 2.6 

  I recommend a swap between 2.5 and 2.6. Showing what the Metadata
looks like to consolidate in the reader's mind what all those mark up
means, before considering the case where Jo does not have control over
her markup and requires a slight modification to the mark up. It hammers
in the fact that the metadata the reader has just seen previously does
not change at all by modifying the location of the namespace
declarations.


Section 3

Section 3.1

  While in Section 2 there was a good reason for wanting to mark up the
html: "...readers of her blog might be able to add her talk directly to
their calendar.". It seems by comparison the original example in Section
3, while it contains enough material to cover a variety of RDF/A
features, lacks some weight with respect to "Why would I want to mark
that up?". 

  I guess I am focusing on the sentence: "Shutr may benefit from using
RDF to express this rich metadata." - my question is: what benefits? I
cannot think of one right now but if we could find some it will engage
the reader even more to read on. For example: the benefit is to afford
more accurate retrieval for photos by specific photographers, or else...

Section 3.2

  Awkward sentence (?): "One might wonder, given the above example, if
the span element is required to attach RDF properties to rendered
content. In fact, it is not: the property attribute can be used on any
XHTML element. For example, if the original HTML did not include the
explicit words "Photo Album #12345":"

  Suggestion: It is probably clearer to say that one can directly mark
up the entire content of a tag such as <h1> using "property". Use "span"
if there are something in that element you want to include/exclude.


Section 4:

Section 4.3 

  Suggestion: Here is a good place to introduce the similarities and
differences between span/anchor and meta/link without much effort.
Inserted my editing suggestion between [] below:

  "One immediately wonders whether the redundancy between the about and
id attributes can be simplified. Partly for this purpose, RDFa includes
elements link and meta, [which is similar in function to anchor and
span, but] behave in a special way: they only apply to their immediate
parent element, even if an ancestor element bears an alternate about
attribute." 




-----Original Message-----
From: Ben Adida [mailto:ben@mit.edu] 
Sent: Wednesday, April 26, 2006 7:31 AM
To: Gary Ng
Cc: public-rdf-in-xhtml task force
Subject: RDFa Primer WD#2 Ready - Addressing Gary's Comments from WD#1


Gary,

The Primer is ready for you to review at:
http://www.w3.org/2001/sw/BestPractices/HTML/2006-04-24-rdfa-primer

(you'll need a Mozilla-based browser to see it, as it's XML with XSLT).

Though I already responded to your comments earlier [1], I wanted to  
point out exactly which ones we incorporated into the latest draft  
and how. I've tried not to repeat too much of [1].

-Ben

[1] http://lists.w3.org/Archives/Public/public-swbp-wg/2006Jan/0085


> 1) Overall Organization
> =======================
>
> Would it be beneficial for the reader to have some brief  
> introduction on
> basic constructs, before diving into how they are used in the use  
> case?

We introduced and significantly reworked Section 2, which we think  
addresses this concern.

[...]
>     - "How about annotating tables, frames, forms and dynamic content
> from scripts producing menus and flash?"

We don't have examples of this kind only because these are more  
advanced, but we hope to integrate at least form annotation before  
this Primer goes to W3C Note status.

>     - "How do I create chains of triples?" For example, an address  
> of a
> person (Mark in the example), represented by an annoymous node,  
> which in
> turn has statements specifying triples making up the address.

We will probably not address this in the Primer, as the it is mostly  
directed at HTML authors for whom "a chain of triples" is likely not  
the first topic they have in mind. That said, we certainly hope that  
interested readers will continue to the RDFa syntax, which will be  
normative in XHTML2, as you noticed:

[...]

> ------------------------------
>
> 1.1) In the preliminaries, the following sentence may provide some
> initial context to the reader.
>
>      "An XHTML document marked up with RDF/A constructs is a valid  
> XHTML
> Document. RDF/A is about using XHTML compatible constructs and
> extensions to specify RDF 'content'. It is not about embedding RDF
> syntax into XHTML documents."
>
> ------------------------------

We've added such a paragraph.

[...]

> 1.3 Perhaps the primer should be arranged with a target reader in  
> mind.
> For example, to arrange from the point of view of an HTML author  
> wanting
> to find out how to add annotations to his/her docs, in the quickest  
> time
> possible.

[... description of what an HTML author might want to do ...]

The new section 2 should address this well.

[...]

> 2) RDF/A itself.
> =============================
>
> I must say at first glance I found the approach extremely confusing.

Let us know if this new version helps make it less so :)

We did not address a number of the issues in this section, as we want  
to keep RDFa simple, and not try to resolve issues that may be  
general to all RDF serializations.

However, we did more thinking about issue 2.4, with IMAGE and OBJECT  
elements. Currently, we believe that the SRC attribute designates an  
object, not a subject, of a triple. It is, in fact, much like href.  
For example, "this is my foaf:img" is:

<img rel="foaf:img" src="ben.jpg" />

Note also that we cannot rely too much on what's inside the <img>  
element, as that is only supposed to be rendered when loading the  
image fails.

To use the SRC as a subject, one could use the REV property.

More on this on our issues list:
http://www.w3.org/2001/sw/BestPractices/HTML/2005-current-issues#src

Note also that we *do* want to add additional examples, like form  
annotation, before we go final with this note.

-Ben

Received on Monday, 15 May 2006 17:05:18 UTC