- From: Clark, John <CLARKJ2@ccf.org>
- Date: Tue, 17 Jul 2007 15:43:52 -0400
- To: public-grddl-wg@w3.org
I took an action to review the documentation for the xml-attributes library: [NEW] ACTION: john-l to read through documentation for xml-attributes and to be sure there aren't any gremlins. [recorded in http://www.w3.org/2007/07/11-grddl-wg-minutes.html#action04] The review follows below; I believe that this completes this action. <review resource="http://www.w3.org/2003/g/xml-attributes"> ========================================================= Review of "Extracting XML attributes for RDF using GRDDL" ========================================================= Overall comments ---------------- I am wary about this entire module because of the known and aknowledged dragons that would cause output production to stop (and thus fail) completely. Aside from that, I still think I would have a hard time using this library based on its documentation. Introduction section -------------------- - What does "When there is no information, the templates do not produce attributes." mean? Advanced xml:lang ----------------- - "In the case when a parent or other ancestor element in the output, has (possibly) had xml:lang or xml:base values defined" -> "In the case when a parent or other ancestor element in the output has (possibly) had xml:lang or xml:base values defined" Rationale: punctuation fix - 'In the xml:lang case, the template does not normally produce xml:lang="" attributes, so that if a parent has being given an xml:lang, since the child node, may have no language, the correct use, is to first set xml:lang to "", and then to call the named template, following the documentation for xsl:attribute, this will overwrite the value "".' Commentary: I don't really know how to parse or otherwise make heads or tails of this. Please help. Advanced xml:base ----------------- - 'with an xsl:message terminate="yes"' -> 'with an xsl:message terminate="yes".' Rationale: end the sentence with a full stop - 'If present, this must be the "node" parameter passed to the xa:base or xa:base-and-lang template used on the closest ancestor, in the output, to the current output element that potentially defines an xml:base. This node, and its ancestors are ignored, when computing the correct value of xml:base. This is for the case, when a parent element in the output, has already had an xml:base attribute generated, using the "node-used-by-ancestor" node. In some cases, failure to use this parameter may result in the same relative path being output in two nested places, which gives the incorrect result.' -> 'If present, this must refer to the same node as the "node" parameter passed to the xa:base or xa:base-and-lang template that is used on the closest ancestor-in the output-to the current output element that potentially defines an xml:base. This node and its ancestors are ignored when computing the correct value of xml:base. This is for the case when a parent element in the output has already had an xml:base attribute generated using the node specified by the "node-used-by-ancestor" parameter. In some cases, failure to use this parameter may result in the same relative path being output in two nested places, which gives the incorrect result.' Rationale: attempt to fix the comma-itis and clarify a few points Commentary: this is still difficult to understand, although thankfully there is an example. - 'in order to reduce the potential for input that has too many relative references' -> 'in order to reduce the potential risk for input that has a large number of relative references' Rationale: attempt to make the phrase more sensical; the original author should carefully consider this change Description of Implementation ----------------------------- - 'In the advanced case, the correct set of ancestors to ignore, is computed using the "node-used-by-ancestor".' -> 'In the advanced case, the correct set of ancestors to ignore is computed using the "node-used-by-ancestor" template.' Rationale: punctuation and phrasing fix Implementation -------------- Looks like it does what it says on the tin, but it'd have to be a big tin. </review> Take care, John L. Clark | Systems Analyst | Cardio-Thoracic Surgery Research Cleveland Clinic | 9500 Euclid Ave. | Cleveland, OH 44195 | (216) 445-6011 =================================== Cleveland Clinic is ranked one of the top hospitals in America by U.S. News & World Report (2007). Visit us online at http://www.clevelandclinic.org for a complete listing of our services, staff and locations. Confidentiality Note: This message is intended for use only by the individual or entity to which it is addressed and may contain information that is privileged, confidential, and exempt from disclosure under applicable law. If the reader of this message is not the intended recipient or the employee or agent responsible for delivering the message to the intended recipient, you are hereby notified that any dissemination, distribution or copying of this communication is strictly prohibited. If you have received this communication in error, please contact the sender immediately and destroy the material in its entirety, whether electronic or hard copy. Thank you.
Received on Tuesday, 17 July 2007 19:44:12 UTC