search

w3c / payment-request

Payment Request API
https://www.w3.org/TR/payment-request/
Other
486 stars 133 forks source link

Editorial: Section 3 sentence very hard to read #839

Closed rvm4 closed 5 years ago

rvm4 commented 5 years ago

The first paragraph after the NOTE block in section 3 (19th page) is incredibly hard to read. I don't have much context on the concept it is describing, so I didn't feel confident I could write an accurate and cleaner sentence.

marcoscaceres commented 5 years ago

I guess you are referring to this spaghetti🍝:

A request's payment-relevant browsing context is that PaymentRequest's relevant global object's browsing context's top-level browsing context.

I agree it reads like total gibberish... but it's technically accurate. It make sense inside the context of a web browser engine: as the concepts map to things in the HTML spec... which themselves then map back to appropriate security checks inside the browser implementation.

If it's ok, I'd be inclined to leave it. We have a bunch of tests that validate that behavior (basically it relates to iframe and pop-windows).

ianbjacobs commented 5 years ago

@rvm4,

I made a similar comment previously [1]. I had suggested "The payment-relevant browsing context of a PaymentRequest is the top-level browsing context of the relevant global object."

At that time @marcoscaceres similarly indicated a preference to leave it as is.

Ian

[1] https://github.com/w3c/payment-request/pull/811#pullrequestreview-193347605

domenic commented 5 years ago

Personally I find sentences of the form "X's Y's Z's W" simpler than "the W of the Z of the Y of the X" for various reasons. One important one is that it corresponds closer to the computer code that implementers would be typing for this, which is roughly X.Y.Z.W.

ianbjacobs commented 5 years ago

@domenic I knew you were really a machine!

marcoscaceres commented 5 years ago

I'm going to go ahead and close this as "won't fix." Hope that's ok.