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
