Re: Spec review

On Tue, 2007-02-13 at 14:57 -0500, Clark, John wrote:
> I worked my way through the normative sections of the GRDDL spec; the
> following are my comments on the most recent editor's draft.  I believe
> this completes my action: [[ACTION: JohnL comments on spec]].
> 
> Comments on GRDDL editor's draft, version 1.208[4]
http://www.w3.org/2004/01/rdxh/spec

Thanks for the careful review.

change summary:
Revision 1.209  2007/02/13 21:36:16  connolly
wordsmithing, punctuation, typo fixes

I applied your edits verbatim except as noted below...


> 2. Adding GRDDL to well-formed XML[1]
> -------------------------------------
> 
>   - "The glean_title.xsl resource specifies a function from XPath
> document
>     nodes to RDF/XML documents, and hence to RDF graphs; This function
> is
>     the property referred to as the transformation property of the XSLT
>     document."
>     ->
>     "The glean_title.xsl resource specifies a function from XPath
> document
>     nodes to RDF/XML documents, and hence to RDF graphs; this function
> is
>     the property referred to as the transformation property of the XSLT
>     document."
> 
>     Reason: capitalization fix
> 
>     Comment: I might say "this function is known as the transformation
>     property" or "this function is called the transformation property",
>     but YMMV.

yes, "... is called..." is nicer...


> 3. Using GRDDL with XML Namespace Documents[2]
> ----------------------------------------------
> 
>   - "To associate a GRDDL transformation with a whole dialect, have the
>     namespace document include the grddl:namespaceTransformation
>     property."
>     ->
>     "To associate a GRDDL transformation with a whole dialect, have the
>     GRDDL result for the namespace document associate the
>     grddl:namespaceTransformation property with the namespace resource."
> 
>     Reason: make clear the fact that the grddl:namespaceTransformation
>     property is actually found in a GRDDL result for the namespace
>     resource

(a) I'm not sure it's really more clear to most readers
(b) the rules that follow are the 100% clear version
(c) it's incorrect; "the GRDDL result" presumes there's exactly 1, when
there are in fact 0 or more.


>   - This section notes that "the result of parsing an RDF/XML document
> is
>     a GRDDL result of that document".  Is this a logical consequence of
>     the preceding rule, or simply an assertion of the spec?

it's asserted in the next rule.

>   I ask
> because
>     the section calls it a "degenerate case", which seems to imply that
> it
>     follows from the preceding rule, but I can't see how that might be
> the
>     case.

ok, I'm changing "degenerate case" to "base case".


>   - The diagram "using GRDDL with an XML Schema" shows a solid
>     "transformation" directional link from po-doc.xml to grokPO.xsl,
> which
>     seems to indicate that po-doc.xml refers to this GRDDL
> transformation
>     directly, but instead it gets this GRDDL transformation indirectly
>     from GRDDL processing of the namespace document.

yes, I used to have dotted lines for implicit transformations, but
when I updated the diagrams, I didn't manage to keep that feature.


>   - Would a document author ever want to explicitly turn off this
> feature,
>     so as to prevent namespace transformations from being processed?

Not in the use cases we have explored so far. That would
be a substantive design change; feel free to request an
issue, but beware we're trying to make end-game noises
around here. :)

>   - Subsection "Using GRDDL with an XML Schema namespace document" seems
>     to give special status to XML Schema namespace documents, but
>     shouldn't the specification clearly indicate that the same applies
> for
>     any XML namespace document?

I changed the section heading to
 Example: Using GRDDL with an XML Schema namespace document

I hope that suffices.


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

Received on Tuesday, 13 February 2007 21:41:52 UTC