Re: [access-control] editorial comments

On Wed, 18 Jul 2007 16:51:51 +0200, Matt Womer <mdw@w3.org> wrote:
> I was just finally reading the terrific access control document []  
> (thanks for pointing it out to the POWDER group) and had some editorial  
> comments.

Thanks!


> [...]
>
> web should always be capitalized as Web

Done for now.


> 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

I think the fallback to emphazing (which is also used when RFC 2119 is  
reference) is good enough.


> 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)

Changed.


> Reference tags and links should probably be done in the fashion  
> mentioned in []

Isn't this already the case?


> 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

A distinct typeface is used.


> Section by section editorial thoughts:
>
> SoTD:
> Is this a Rec track document?  I think that should be made clear here.

Any suggestions on how to do that? FWIW, I looked around to other drafts  
of which I know they are headed for Rec at some point in time and they  
don't have it either (css3-multicol, XMLHttpRequest).


> 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?

Everything sentence with an RFC2119 term in it (properly marked up) is  
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.

Yeah, not sure what to do about that yet.


> 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.

I'm not sure what this means.


> 1.2:
> "by denying access (to untrusted content)" I think the parens are  
> unnecessary

Ok, removed.


> "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.

Added a reference. I haven't expanded the term as I'm planning to fold in  
security with the rest of the document in due course.


> 2:
> Am I missing something obvious regarding only using HEAD and GET and not  
> POST?

This will be revised hopefully soonish to allow for any method. Although  
the initial request will always have to be done using GET.


> "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.

It's part of the definition of subdomain. Made it more clear now.


> The linking on 'access item' seems excessive in section 2.0, which link  
> back sometimes just two or three sentences

Removed some.


> What makes some text a green Note?  Is that there as a note about TBDs,  
> or on going discussion or something particularly important?

That's just styling of notes, which are non-normative.


> What is the meaning of the yellow background?

It highlights a more important part of the code in question given the  
context.


> 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

Fixed both, hopefully.


> 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?

No. They don't represent code. They are just values of a flag.


> I'd love to see an example or two run through this algorithm.

Me too! At some point in time it will get examples.


> 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.

I'd rather have implementors study the draft than use shortcuts as using  
shortcuts leads to errors which you do not want here. However, if someone  
procudes something like that it might be worth considering.


-- 
Anne van Kesteren
<http://annevankesteren.nl/>
<http://www.opera.com/>

Received on Monday, 30 July 2007 12:35:28 UTC