- From: Matt Womer <mdw@w3.org>
- Date: Wed, 18 Jul 2007 15:51:51 +0100
- To: public-appformats@w3.org
- Cc: annevk@opera.com
Hi WAF Folks, I was just finally reading the terrific access control document [1] (thanks for pointing it out to the POWDER group) and had some editorial comments. I haven't seen any [access-control] marked comments on this list, so my apologies if this is the wrong place. A number of these comments come from the W3C Editor's Style Guide [2] and are pretty nitpicky. Please understand I appreciate the document and it is in good shape, but I figured since I read it, I might as well comment on it. Also, please don't assume that the Style Guide related changes requested here, if accepted, makes the document match everything in the Style Guide, these were just things I knew were in the Guide as I read your document. -- Throughout: web should always be capitalized as Web [3] RFC 2119 keywords have a suggested markup in the guide that works well, since it puts them in italics and lower case using CSS, but fails back to capitalized, see [4] Spelling should be American English, e.g. Acknowledgements should be Acknowledgments (most specs ignore this, I didn't do any other spell checking, just noticed this in the TOC) [5] Reference tags and links should probably be done in the fashion mentioned in [6] Use of color should be considered carefully, and ensure there is some other way that they are distinguished when printed on black and white printers, or for someone who may be color blind Section by section editorial thoughts: SoTD: Is this a Rec track document? I think that should be made clear here. 1: I'm not sure why the Conformance section is within the Introduction, or why Terminology is within Conformance? Is the introduction informative or normative? 1.1: "A conformant specification..." sounds odd. I realize it becomes clearer once you read more of the document, but it's especially hard to parse when the word 'specification' is also used to refer to this working draft/recommendation within the same sentence. 1.1.1: The terminology section might be expanded to add conventions on the use of color as well as adding some more of the terms used within. 1.2: "by denying access (to untrusted content)" I think the parens are unnecessary "property interpret IDNs" should probably reference something on IDNs, perhaps the IDNA reference? I know that's been linked to once already at this point in the doc, but not where the term IDN is introduced. I would also expand this first usage of IDN. 2: Am I missing something obvious regarding only using HEAD and GET and not POST? "In addition to matching the above EBNF the ToASCII algorithm must apply successfully (without errors) to each label component of the subdomain (if any) from the access item" I think this is the first point where the term label is used, and it is unclear what it means at this point. The linking on 'access item' seems excessive in section 2.0, which link back sometimes just two or three sentences What makes some text a green Note? Is that there as a note about TBDs, or on going discussion or something particularly important? What is the meaning of the yellow background? 2.1: "Although files containing such processing instructions HTTP headers can be set accross an entire server making them far more effective. " is missing a word or two that makes this sentence make sense, also 'accross' is typo-ed 3: I'm not sure I understand the markup of code yet, but I think "false" and "true" should be red code in the "allow access flag" section? I'd love to see an example or two run through this algorithm. The document ends abruptly. I don't think there's much more to say, it just seems a bit abrupt. I would like to see maybe an appendix where the inline EBNFs and perhaps a more formal representation of the algorithm could be placed for handy reference for implementors. Thank you! -Matt Womer POWDER Team Contact References: [1] http://www.w3.org/TR/2007/WD-access-control-20070618/ [2] http://www.w3.org/2001/06/manual/ [3] http://www.w3.org/2001/06/manual/#Terms [4] http://www.w3.org/2001/06/manual/#RFC [5] http://www.w3.org/2001/06/manual/#Spelling [6] http://www.w3.org/2001/06/manual/#References
Received on Wednesday, 18 July 2007 14:53:31 UTC