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

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ Susan Lesch <lesch@w3.org> was heard to say:
| 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,

I added an appropriate terminology section. I replaced "whitespace"
with "white space". I fixed the references. Building chunked versions
of the spec and fixing the other style details is something that I
will address before we go to Proposed Recommendation.

                                        Be seeing you,
                                          norm

- -- 
Norman.Walsh@Sun.COM / XML Standards Architect / Sun Microsystems, Inc.
NOTICE: This email message is for the sole use of the intended
recipient(s) and may contain confidential and privileged information.
Any unauthorized review, use, disclosure or distribution is prohibited.
If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>

iD8DBQE/skyjOyltUcwYWjsRAtLgAJwPGTw98IcoyZZ/P6WGy1NQP9mfzQCgqQUm
evkR5vaW7wP+HpF1QH8f6cM=
=qnkk
-----END PGP SIGNATURE-----

Received on Thursday, 13 November 2003 20:19:41 UTC