W3C home > Mailing lists > Public > public-qt-comments@w3.org > July 2003

Comments for WD-xpath-datamodel-20030502 and WD-xpath-functions-20030502

From: Susan Lesch <lesch@w3.org>
Date: Mon, 30 Jun 2003 23:45:55 -0700
Message-Id: <p05111b0bbb26d883b35a@[192.168.123.158]>
To: public-qt-comments@w3.org

Hello,

These are quick comments for your "XQuery 1.0 and XPath 2.0 Data
Model" [1] and "XQuery 1.0 and XPath 2.0 Functions and Operators" [2]
Last Call Working Drafts.

Overall they are beautifully done!

Both specs appear to need a conformance section. Here is a thought in
that direction. Functions and operators defines "must" and "may" in
Terminology, and this is fine. I am more worried about the data model.
It should say:
     The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD",
     "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
     document are to be interpreted as described in [RFC2119].
(from http://www.ietf.org/rfc/rfc2119.txt) or, it should say what
definitions are being used (e.g., dictionary definitions). It could
also say why the RFC is not used. See the W3C Manual of Style for a
markup suggestion (http://www.w3.org/2001/06/manual/#RFCs).

At .99MB the functions and operators file is too large. It took more
than a minute to load in Mac IE OS 9 and gave a read/write error trying
to save the file to disk. I suggest breaking the spec into chapters,
and then providing a single file (for print, for clicking within the
document and for searching).

Running the data model through Tidy with indent off would save 80-90k,
or over 25%. For functions and operators, this Tidy setting saves 290k,
again over 25%.

Functions and operators seems to be using an old XMLspec stylesheet.
This CSS rule was removed in August 2002 because of rendering problems
(section F1 and some of the definitions are tough to read in Mac IE;
screen shot on request). I suggest upgrading to a later XSLT.
     dt.label       { display: run-in; }

For both drafts, the title of a reference should be the link. For
example:
     <dd>World Wide Web Consortium, <em>Namespaces in XML</em> See <a
     href="http://www.w3.org/TR/REC-xml-names/"
     >http://www.w3.org/TR/REC-xml-names</a>.</dd>
becomes something like this:
     <dd>World Wide Web Consortium, <cite><a
     href="http://www.w3.org/TR/REC-xml-names/">Namespaces in
     XML</a></cite> on-line at http://www.w3.org/TR/REC-xml-names.</dd>

The Manual of Style shows details for references markup
(http://www.w3.org/2001/06/manual/#References).

Generally, white space is two words. This applies to both drafts (see
http://www.w3.org/TR/REC-xml#sec-common-syn).

In section D of the data model, the green #00CB9C class .element is
dark with black text. #85e9b1 instead (I am sure you can do better than
my color picking) would give some contrast.

[1] http://www.w3.org/TR/2003/WD-xpath-datamodel-20030502/
[2] http://www.w3.org/TR/2003/WD-xpath-functions-20030502/

Best wishes for your project,
-- 
Susan Lesch           http://www.w3.org/People/Lesch/
mailto:lesch@w3.org               tel:+1.858.483.4819
World Wide Web Consortium (W3C)    http://www.w3.org/
Received on Tuesday, 1 July 2003 02:46:03 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 7 January 2015 15:45:13 UTC