[access-control] editorial comments

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