Re: GRDDL Spec Review

On Sun, 2006-10-22 at 03:36 +0100, Harry Halpin wrote:
> I promised to review the GRDDL Spec before release, and so here it is.

I think I have worked thru all these comments now.

http://www.w3.org/2004/01/rdxh/spec 
1.136  2006/10/23 18:58:21

I made a number of the editorial changes you suggested. One
of them (DTD/Schema) would have been a substantive change,
and I didn't make that change.

Details...

[...]
> 3) "And how can software determine whether authors of each are in fact
> the same person?" -> "How can software determine whether authors of each
> are in fact the same person?"
> 
> I'm pretty sure it's good style not to begin a sentence with "and"

It's good style to break the rules now and again.

> 4) "A Primer[primer] <http://www.w3.org/2004/01/rdxh/spec#primer> is a
> [progressive] tutorial on the GRDDL mechanism" ->
> "A Primer[primer] <http://www.w3.org/2004/01/rdxh/spec#primer> is a
> [step-by-step] tutorial on the GRDDL mechanism
> 
> "Progressive"? As in politically? Let's just say "step-by-step" to keep
> it clear.

Er... OK.

> 5) "GRDDL (Gleaning Resource Descriptions from Dialects of Languages), a
> mechanism for getting RDF data out of XML documents and in particular
> XHTML pages using explicitly associated transformation algorithms. These
> use cases also illustrate how XML and XHTML documents can be decorated
> with microformat, Embedded RDF or RDFa statements to support GRDDL
> transformations in charge of extracting valuable data that can then be
> used to automate a variety of tasks." ->"GRDDL. These use cases
> illustrate how XML and XHTML documents can be decorated with
> microformat, Embedded RDF or RDFa statements to support GRDDL
> transformations in charge of extracting valuable data that can then be
> used to automate a variety of tasks."
> 
> Just delete the re-definition of GRDDL. If the user has read the
> introduction they already understand what GRDDL is :)

Thanks. Clearly I have read this too many times.

> 5) "XML DTD" -> "XML DTD or schema."
> 
> Just to keep RELAX NG and XML Schema folks happy.

No, the constraint really is specific to DTDs.

> 6) "and to emphasize the data-centric focus of the RDF/XML view." ->
> I would just delete, since I have no idea other than how using the word
> "data" using the namespace prefix "data-transformation" emphasizes
> "data-centric" focus,

Er... it seems obvious, to me.

>  but regardless "RDF/XML view" -> "RDF view"

RDF/XML is also correct, in this case. I'm inclined to leave it.


> 7)The question over what actually is supposed to go into a namespace
> document is wide open, so maybe just add in " could be anything" :
> "a namespace document may have an XML Schema representation or an RDF
> Schema representation, or perhaps both, using content negotiation
> <http://www.w3.org/TR/webarch/#def-coneg>." -> "a namespace document can
> be a variety of documents, such as RDDL[CITE THIS]. A namespace document
> may be or link to an XML Schema representation or an RDF Schema
> representation, or perhaps both, using content negotiation."

It already says "For example...". I'm not inclined to make this change.


> 8) This sentence seems a bit, well, too brief and therefore confusing
> given the following formal bit:
> 
> "To associate a GRDDL transformation with a whole dialect, use the
> |grddl:namespaceTransformation| property." ->  "To associate a GRDDL
> transformation with a whole dialect, have the namspace document include
> the  |grddl:namespaceTransformation | RDF property. The precise methods
> for allowing various types of namespace documents to include this
> property are detailed below, first formally and then by example."

Yes, that's good.

> 9)  Isn't "the resource identified by ?NS " the namespace document? Then
> why not introduce ?NSDOC there?

I'm not sure. I'm not inclined to change it in a rush, though.
Perhaps make time in a WG teleconference for me to present the
rules?


[...]
> So, just to check my first reading understanding:
> 
> "if an information resource ?D has an XML representation whose root
> element has a namespace name ?NS then any GRDDL result of the resource
> identified by ?NS is a GRDDL result of ?D"
> 
> "This  means that if the source document has a root element that has a
> namespace, then the  result documents of the namespace document of the
> namespace are also the result document of the source document. "

Yes, that's consistent with the formal rule. But as Ben
pointed out, I'm not sure it's what we want. So I'm not
changing this.

[...]
> I'll look at the N3 Rules tomorrow to see if I grok them.

I look forward to that.


> 10) "For example, consider this privacy policy written in P3Q, a
> contrived analog to P3P[P3P] <http://www.w3.org/2004/01/rdxh/spec#P3P>:"
> -> This isn't  a suggested change for the WD, but a note for  future
> releases. It would be *much* better if we didn't have to use a
> "contrived "analog" and could do using a deployed XML language.

Yay and verily.

> 11) Exactly what section is this referring to?

the section it's in.

>  "Using GRDDL with an XML
> Schema namespace document"? If so, let's say it upfront:
> 
> "The Working Group is likely to add a section to the GRDDL primer much
> like this subsection. Since this subsection has no novel normative
> material, we're interested in feedback on whether it should remain part
> of this specification once it is covered by the primer." -> "The Working
> Group is likely to add a section to the GRDDL primer much like the
> subsection "Using GRDDL with an XML Schema namespace document" given
> below.

except it should be "above".

>  Since this subsection has no novel normative material, we're
> interested in feedback on whether it should remain part of this
> specification once it is covered by the primer."

I think I'm leaving it as is, pending further inspiration.



> "Also you don't mean GRDDL Primer, or do you?

Yes, I do.

>  Do you mean
> "specification"? Just making sure. If you really do mean primer, perhaps
> we should remove this from the spec and put it in the Primer before
> releasing the GRDDL WD.

My time machine is broken.

>  It's just confusing to have a bit of the spec
> that says "Well, this is interesting, it might appear in another
> document later..." I mean, I assume once the press release works out
> people will also look at the primer again.
> 
> 12) Ditto for the next "likely to add a section" bit.
> 
> 13) "value is a URI reference that refers to an executable script or
> program which is expected to transform the source document into an
> RDF/XML rendition." -> "RDF rendition" instead of "RDF/XML rendition"

done earlier.

> 14) This method is suitable for use with valid XHTML documents which are
> constrained by an XML DTD."-> "XML DTD or schema" instead of just "XML
> DTD".

nope.

> 15) "meta-data in RDF/XML in a way that preserves the meaning of the
> document" -> "metadata in RDF in a way that preserves the meaning of the
> document"

yes.


> 16) "In the figure below, the arrow labelled info relates a document to
> an abstract notion of the information contained in the document. " ->
> Note that this should be moved up in spec to the first point where we
> use the "info" line, i.e. the possibly to be moved "Using GRDDL with an
> RDF Namespace document" setion.

I added a note in the status section that the figures need work.


> 17) There's a singular/plural type here:  " a available representations
> " -> "available representations." Just delete "a"

yes.

> 18)"define a an XHTML profile." -> "define an XHTML profile." Can't have
> both "a" and "an" at once.

done.

> 19) Is it okay to use "embedded RDF statements" in a W3C WD as they are,
> well, non-standard?

They're no less standard than class="head" or any markup like that.
In fact, they're somewhat more standard, since they're grounded
in URI space.

>  I'm not sure. I like Embedded RDF personally, but
> just a note. Also, why is the entire "The GRDDL Vocabulary" section in
> the Rec?

Because it's part of the specification of GRDDL; it's something
reviewers of the GRDDL specification should read.

>  Shouldn't it be in the profile/namespace doc for GRDDL and then
> reference from the Spec???

Perhaps... didn't we talk about this already? Maybe I'm remembering
a side conversation with Ian. I'm inclined to include it by copy.
It needs work, and including it by copy seems to emphasize that.


-- 
Dan Connolly, W3C http://www.w3.org/People/Connolly/
D3C2 887B 0F92 6005 C541  0875 0F91 96DE 6E52 C29E

Received on Monday, 23 October 2006 19:00:45 UTC