Re: Review of Primer part 1

All edits incorporated so far.

Danny Ayers wrote:
>
> Version 83. All minor editorial here.
>
> I've got as far as the first SPARQL example, there's at least one
> mistake there (6 variables in query, only 4 in result), will
> check/send correction shortly.
>
> = General comments =
>
> Here and there the English could be plainer - quite a few long
> sentences that could probably be split up
>
> Aside: had a friend here last week who knew the purpose of GRDDL but
> hadn't looked into the details. I had the Primer open, so tried to go
> through the different approaches from there. Couldn't really, had to
> refer back to the spec right away. I don't think this suggests any
> change to the primer, but anyone with time on their hands might
> consider making a separate (informative) A4 cheatsheet like these:
> http://www.dajobe.org/2005/04-sparql/
> http://ebiquity.umbc.edu/resource/html/id/94/
>
>
> *** Introduction
> "uniform XML dialects" - is it reasonably obvious what these are? (I
> don't know)
Now: GRDDL provides an inexpensive set of mechanisms for bootstrapping
RDF content from XML and XHTML. GRDDL does this by shifting the burden
of formulating RDF away from the author to transformation algorithms
written specifically for XML dialects such as XHTML.
> -
>
> "...a standard transform library has been provided that can extract
> RDF that's embedded directly in XML or HTML using <rdf:RDF> tags as
> well as extract any profile transformations."
>
> I suspect this is confusing - sounds like you might be looking at:
> <html>
> ...
> <rdf:RDF>....</rdf:RDF>
> ...
> </html>
>
> Can't think of good alternate text offhand, sorry
Don't know of any myself, so just added link to example at:
> -
>
> "In this document the term HTML is used to refer to the XHTML dialect
> of HTML."
>
> I suggest moving this line to follow the first sentence of the
> Introduction.
done
> *** Scheduling a Meeting
>
> s/Scheduling a Meeting/Example : Scheduling a Meeting
>
I made all the titles for sections more self-describing instead.
> (para after code block)
> "In HTML, profiles are used to link documents to descriptions of the
> metadata schemes they employ."
> =>
> "In HTML, profiles are used to link documents to descriptions of the
> metadata schemes they emplo (see HTML specification, <a
> href="http://www.w3.org/TR/html401/struct/global.html#h-7.4.4.3">Meta
> data profiles</a>)."
done
> -
>
> "She can either write her own transformation or re-use an existing set."
> =>
> "She can either write her own transformation or re-use an existing
> transformation, in this case there's one available for calendar data."
>
> (Not sure about that replacement text, but the current version does
> seem a bit unclear).
>
> -
>
> example at:
> http://www.w3.org/2001/sw/grddl-wg/doc29/robin-hcal-grddl.html
> confirmed working with local xslt & Dom's online demo
>
> -
>
> *** Referencing Via Profile Documents
>
> s/Referencing Via Profile Documents/Using Profile Documents ?
>
> (or maybe "Referencing through Profile Documents"? - it currently
> seems a bit arcane)
Chose "Through"
> -
>
> (first para)
> "This is done by referencing GRDDL transformations in a profile
> document referenced in the head of the HTML or namespace document for
> XML vocabularies in general."
> =>
> "This is done by referencing GRDDL transformations in a profile
> document referenced in the head of the HTML. Other XML vocabularies
> may use their namespace documents for the same purpose."
>
> (again, not sure about the replacement, but the original seems a bit
> clunky)
done.
>
> "Yet this is a good use of time, since once the tranformation has been
> linked to the profile or namespace document, all the users of the
> dialect get the added value of RDF."
>
> s/Yet/But ?
Better to use "Yet" rather than begin sentence with "but" by my
grammatical training :)
> s/tranformation/transformation
done
> (soon after)
> s/tranforamtion/transformation
done
> -
>
> "Microformat-enabled web-pages on the Web may not be valid XHTML..."
>
> move this to the end of the introduction? format as block note?
Hmm...like it where it is, since we introduce it *after* introducing
microfmats. Thinking about block notes. If we have more "general advice"
in Primer, I will add block notes, but just don't want to add only one
block note in entire primer.
> -
>
> "a process that is tiresome and often prone to human error"
> =>
> "a process that is tiresome and prone to human error"
done
> -
>
> (the SPARQL)
> newline prior to SELECT
>
> could do with a little explanation
Any ideas? Would like text.
> (to be continued...)
>
>

Please test all examples as well, using a GRDDL-aware client if possible
and whatever other RDF tools we specify in the text. Please also get me
the second part of the review ASAP.

-- 
  -harry

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

Received on Sunday, 24 June 2007 20:04:47 UTC