Primer Review

Overall, good - I think it's ready to ship as a working draft with the
following minor syntactic changes.

I'd also *really really* like to have working sample "example" files
with data and links to engines like SPARQL and GRDDL implementations
which people can run "out of the box", which we don't for much of this
tutorial. IMHO that's the main  distinction between the tutorial and the
use-case document, so let's do it. Anyone up for helping? However, I
won't block the release of this document as Working Draft even though
the examples need more work.

General note: There's lots of sentences like this: "Since XFN values are
found on 'a' elements, " that should be formatted like this:

"Since XFN values are found on <code>a</code> elements," for
transparency.

I'll note them as I encounter them with the "*-> <code>".. note.


1) Introduction

I really want to start the primer off as "easy-to-read" and am so a bit 
unsure about the rather technical first sentence,primarily because I 
don't believe it's exactly correct, as RDF is not really KR or
meta-data  for many of purposes in our use cases, but just a generalized
data  format that uses URIs for identity keys for easy aggregation.
Instead of  starting a primer with a potentially contentioous statement
(as well as  referencing an "enduring conversation thread" which most
readers of the  Primer may not care about, let's just simplify. I've
also think  re-arranging the paragraph breaks a bit makes it bit easier
to understand - remember the audience may not be people who read this
may not know what "knowledge representation" means nor XSLT mavens.

"XML and RDF technologies address very separate and often orthogonal 
problem spaces: message and structured document formats, meta data, and 
knowledge representation. Publishers of distributed web content meant 
for both human and machine consumption have much to gain from standards
that enable both technologies. The enduring conversation thread on
embedding RDF in XHTML is a demonstration of this itch which (if
properly scratched) has the potential to greatly increase the richness
of web content specifically, and data in general....(first 3 paragraphs")
->
"Publishers of web content meant for both human and machine consumption 
have much to gain from standards that enable both XML and RDF, and by 
taking advantage of both publishers can greatly increase the richness
of  web content specifically and data in general. In particular, there
is a  need to easily convert between XML vocabularies for specialized 
purposes, like XHTML for displaying documents to users, and RDF for 
merging and querying data. GRDDL provides an inexpensive set of 
mechanisms for bootstrapping RDF content from uniform XML dialects in 
such a way as to shift the burden of formulating RDF to transformation 
algorithms written specifically for these dialects.

XML Transformation languages such as XSLT are quite versatile in their 
ability to process, manipulate, and generate XML and the use of XSLT to 
generate XHTML from single-purpose XML vocabularies is historically 
celebrated as a powerful idiom for separating structured content from 
presentation. GRDDL shifts this idiom to a different end: separating
structured content from its authoritative meaning (or semantics). The
way in which GRDDL empowers authors of web content can be considered 
somewhat analogous to allowing a non-native speaker learn the spoken
form of a new language first, before attempting to master its written 
form - rather than trying to learn both simultaneously."

Letting a transformation algorithm convert XML to RDF lets a user not
be  forced to recode the same data in both XML and RDF, instead using
XML  transformation languages such as XSLT that are quite versatile in
their  ability to generate RDF from XML. "

2) Scheduling Example

Who is Jane? :)

"In this use case Jane is trying to schedule a meeting with three other 
friends."
->
"In this use case a hypothetical user Jane is trying to schedule a
meeting with three of her friends."

I know it's pedantic, but let's include the DOCTYPE in our HTML
example,  since otherwise the user can't cut and paste the example and
get it to  validate in the W3C Validation Service:

Add to first example after sentence: "This microformat uses HTML class 
attributes to associate particular meanings with elements in the  markup:"

INSERT->
"<!DOCTYPE html      PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">"

Also, I bet it has to be done on your "after GRDDL" example file as well
[1].

And the markup validtor gives this problem with that document [1] as 
well "on line 19  it contained one or more bytes that I cannot interpret
as  utf-8"

"The profile URI for GRDDL is http://www.w3.org/2003/g/data-view""-> it 
would good explaining to add both a period to the end of that sentence 
and then a sentence explaining what profile URIs are and why they're 
important/nice. However, I seem to have writer's block right now and 
can't phrase it right...maybe say "They provide a uniform place for
links to transformations and documentation to be stored for web-based
vocabularies."

I'd also add the XHTML DTD to your Embedded RDF example, at least in the
linked to example file [2]

I think it would be  nice if we linked to the W3C GRDDL RDF-in-HTML web
service so people  know that it's really running code. [3]

"Then she needs to add a link elemenk" *-> <code>link</code>

"The link element contains" *-> <code>link</code>

 It might be useful to show them the RDF produced (maybe in Turtle
syntax, with a link to Turtle syntax), or at least have a  link to it.

 Finally, the "scheduling calendar" is sort of anti-climatic, because 
we just demonstrated to people that we can take microformats and 
embedded RDF and transform it to RDF/XML. I believe the audience for
this document may very well not be people who are ardent RDF users or
proponents, but general web masters and "desperate perl hackers" that 
might want to know why producing RDF is useful - and they may read the
tutorial up to this point, say "So What?" and then give up.

The best way would be by example.  I think it's okay to go to Working
Draft in final form, but
my (without chair hat on) personal preference would really be to show 
them that the calendar files can be merged and a meeting scheduled via
a  SPARQL query.

3) Buying a Guitar Example

"Stephan wishes to buy a guitar, so decides to check reviews" ->
"Stephan wishes to buy a guitar, so he decides to check reviews"

"Microformats define simple formats which can easily convert between
HTML and RDF through the use of GRDDL" -> I'd link to 
http://www.microformats.org or add a sentence saying "For more
information about microformats please go to http://www.microformats.org"
w/i a link because members of our audience may not know what
microformats are.

"To extract a vCard-RDF from HTML you can use ( @@TODO
hCard2vcardrdf.xsl ???)" -> I'll e-mail Norm Walsh about this and cc the
listserv.

For purely aesthetic reasons:
"<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
  xmlns:rdf  ="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:vCard="http://www.w3.org/2001/vcard-rdf/3.0#"
>    "
-> "<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
  xmlns:rdf  ="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:vCard="http://www.w3.org/2001/vcard-rdf/3.0#">"  

"Another microformat that allows for more information to be gleaned from
the document is XFN" -> link to some URI about XFN.

"Using values in the rel attribute" *-> <code>rel</code>

"Since XFN values are found on 'a' elements," *-><code>a</code>, delete 's.

Again, I would like to link in this XFN example to *full* HTML examples,
not just have HTML code snippets in the code.

"This allows for use to modify the circle of trust from our direct
friends to first-order friends of our friends."

What is "first-order" friends? Friends of Friends? Use different
wording  than "direct friends" and "first order friends" to explain
whatever you're getting at.

"seed URL" -> "seed URI" Also explain what you mean by "seed URI" - I 
think I know but our audience might not.

"That FoaF file will then give us an additional list of URLs " ->
"That FoaF file will then give us an additional list of URIs ". Add a 
sentence explaining that "FOAF (Friend of a Friend) is a popular RDF 
vocabulary for describing social networks of friends and personal  data,
used by services such as Livejournal." Then link to FOAF and 
Livejournal.[4,5].

Using "URL" is not quite as cool as using "URI" :)

"power of the rel="me"" -> "power of the <code>rel="me"</code>"

"The Del.icio.us links" -> The <a
href="http://del.icio.us">Del.icio.us</a> links

<a>because of the rel="me"</a>

While I won't _block_ the transition of this to Working Draft based on 
the fact that it doesn't have links to running code, I might add this 
example does not. I'd like to *run* the example and use this rel="me" 
technique to consolidate identity. Does it actually work? Is it
implemented? If so, where? I vaguely remember reading something Tantek
wrote but can't find the link.

"The Del.icio.us links could be encoded into RDF" -> This is rather 
hypothetical and so more suited for the use-case document. Can we do
this in reality?

And it would be nice to have a "guitar-rocker45" user as well on
del.icio.us to help the code.

"owner "Stephan Smith" who has an RDF-vCard at "example.org" and has
data in other places on other services such as claimid.com and
guitar-rocker.com. All of these can be merged to form a bigger picture
of "Stephan Smith" at "example.org"" -> again, all rather hypothetical.

"Guitar site" -> please make some sample files for this, and possibly a
more informative ficitonal name, such as "GuitarExample.org". Again,
won't block, but making sample files for this needs to be done.

"rel="me" value" *-> <code>rel="me"</code>
 
"Using GRDDL is it possible to glean information about the guitar in
the  form of product specifications supplied by the manufacture and
reviews from site members." ->
"Using GRDDL we can automatically glean information about the guitar  in
the form of product specifications supplied by the manufacture and
reviews from site members."

It's not "possible" - we can :)

"SPARQL engine " -> please add a sentence explaining SPARQL, like  "<a
href="http://www.w3.org/TR/rdf-sparql-query/">SPARQL (The SPARQL 
Protocoal and RDF Query Language)</a> is a query language for RDF 
similar in spirit to the use of the query language SQL for relational
databases."

"If Stephan was looking for a Guitar" -> "If Stephan was looking for a
guitar"

"Using a seeded list of XFN URLs given by Stephan that are converted to 
FoaF, we can match the URLs to any URLs from the FoaF generated from
the  guitar reviews. Now we have a list of members that Stephan trusts 
relative to the guitar site. We can then match the URLs of the
reviewers  to the URLs in the XFN list." ->
"Using a seeded list of XFN URIs given by Stephan that are converted to 
FoaF, we can match the URIs from his XFN list to any URIs from the FoaF 
generated from the guitar reviews. Now we have a list of reviewers that 
Stephan trusts on the guitar review site."

Ala the SPARQL queries, I'd like to actually run them on some data but
I  can't because we don't have any sample files attached that we can 
actually use GRDDL on to generate RDF. It would also be nice, if we 
really want people to learn from this tutorial, to assume they don't
have SPARQL installed, and give them a link to a SQARQL implementation 
such as the one with Jena. 

"This SPARQL result is in XML or JSON and can easily be consumed by 
another application." ->
Again, I won't block, but we really should not just say these sort of 
things but provide a concrete example. Perhaps an example stylesheet 
that generates HTML would be good, or a link to something like the 
Tabulator[6].

I realize I did lots of complaining about there not being links to 
concrete example files. However, over all the content is really good
and  I'm quite pleased. I'm absolutely packed and busy till the end of
the  week, but after the weekend I'm willing to sit down and devote a
whole  day to work closely with someone (Brian Suda I assume, but anyone
else whose interested) in manufacturing these example files.)

[1]http://research.talis.com/2006/grddl-wg/robin-hcal-grddl.html
[2]http://research.talis.com/2006/grddl-wg/david-erdf.html
[3]http://www.w3.org/2003/11/rdf-in-xhtml-demo
[4]http://www.foaf-project.org/
[5]http://community.livejournal.com/ljfoaf/
[6]http://dig.csail.mit.edu/2005/ajar/release/tabulator/0.7/tab.html





-- 
		-harry

Harry Halpin,  University of Edinburgh 
http://www.ibiblio.org/hhalpin 6B522426

Received on Tuesday, 26 September 2006 19:57:07 UTC