Review of xml-attributes library module

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