Re: [css3-images] 2011/12/01 ED section 4.2 review notes

Thanks for the review, Brian!

On Thu, Dec 1, 2011 at 10:21 AM, Brian Manthos <brianman@microsoft.com> wrote:
> # radial gradient is specified by first pinpointing the center
> # of the gradient (where the 0% ellipse will be) then specifying
> # the size and shape of the ending shape (the 100% ellipse).
>
> 1. The prose doesn't align with the grammar like it used to.
>
> In the previous grammars, this prose aligned with the ordering in the grammar...
>        ... (<position>, <size-shape>, <colors>)
>
> I think it's worth considering updating the prose to match the new grammar ordering.

Fixed.  "A radial gradient is specified by indicating the center of
the gradient (where the 0% ellipse will be) and the size and shape of
the <dfn>ending shape</dfn> (the 100% ellipse)."


> 2. Position can no longer be first.
>
> In the prior WD grammar, position was always first.  In the ED grammar prior to 12/28, position *could* be first.  With the current ED grammar it can never be first.

It could only be first if you omitted the shape, and only because the
shape and size weren't connected.  It can still be "first" if you omit
the size and shape entirely.  The possible orderings don't seem
significant to me.


> 3. The meaning and rendering of "simple two length/percent" radial gradients has changed.
>
> WD 09/08
> radial-gradient(25% 25%, red, blue)
> = radial-gradient(25% 25%, ellipse cover, red, blue)
> ~= radial-gradient(25% 25%, ellipse farthest-corner, red, blue)
>
> # ED 11/06
> radial-gradient(25% 25%, red, blue) is invalid
> radial-gradient(at 25% 25%, red, blue)
> = radial-gradient(ellipse at 25% 25% to farthest-corner, red, blue)
>
> ED 12/01
> radial-gradient(25% 25%, red, blue)
> = radial-gradient(ellipse farthest-corner 25% 25%, red, blue)
> radial-gradient(at 25% 25%, red, blue)
> = radial-gradient(ellipse at 25% 25% to farthest-corner, red, blue)
>
> In short, the November ED made the not-keyword-preceded invalid and thus avoided confusing with existing content and conversion while the December ED now makes it valid again but have a completely different meaning from previous WD grammars.
>
> This isn't a catastrophe but introduces pain for little gain, IMO.

On the other hand, the November ED made just-a-size-keyword and
just-a-size-and-shape-keyword invalid, while the December ED returns
it to validity with the same meaning as the previous WD.  Kind of a
toss-up in terms of what different grammars allowed, I think.


> # <shape> || <size>
>
> 4. circle/ellipse keyword can now be repositioned
>
> This isn't so much an issue as just a notation.  Was this intentional?  I thought there were reasons we tried to avoid that in the November ED grammar.

We avoided it in the November ED grammar for readability - we thought
it would have been weird to see something like "to 50% 50% ellipse" or
"at top left circle".  Without the preceding "to", though, there's no
reason to restrict the shape from coming after the size.

It's still prevented from coming after the "at <position>", though,
for the same reasoning as before.


> # The <position> notation is defined by the positioning syntax of 'background-position'
>
> 5. Editorial snafu with <position> prose regarding "defined".
>
> We ran into this issue before:  <position> or <bg-position> should be referred to rather than background-position.  Referencing background-position has the problem that it has layers whereas the <position> parameter of <radial-gradient> does not have layers.

I think you're misunderstanding that comment - it's not "the entire
syntax of background-position", but it *is* defined by the
background-position syntax, as that syntax has a <position>
non-terminal.


> # and the content box as the positioning area.
>
> 6. Editorial snafu with <position> prose regarding "box".
>
> The reference to "content box" is at best confusing here.  I think what you mean is "image positioning area" which maps to "background positioning area" for background-image, and something different for list-style-image and generated content.
>
> The reference to "content box" suggests that radial-gradients used with background-image both ignore the background-clip property AND use a different default (content-box instead of padding-box) when the background-clip property isn't specified.

Yeah, I've been somewhat unsatisfied with the terminology around here
as well.  I've now defined the term "gradient box" to be the image
positioning area and updated all the appropriate uses of "box" in
linear and radial gradients to instead use "gradient box".


> # Same as
>
> 7. "Similar to" is the proper phrasing for the prose within 'farthest-side' and 'farthest-corner'.
>
> Absurd: "Blue is the same as purple except it doesn't have any red."
>
> I already raised this during our November discussions; just broadening the audience.

Just like last time you raised this, I object to changing it.  It's
perfectly normal and sensical English usage.  Further, the use of
"same as ... except" has a stronger implication that the "except"
clause captures *all* of the differences, unlike "similar to ...
except".

I find your "absurd" statement perfectly reasonable, too.  ^_^


> # <length>
> # Gives the radius of the circle explicitly. Negative values are invalid.
>
> 8. We should add a note for authors that speaks to why <percentage> is not included.
>
> It should serve at least three purposes:
> (a) explicitly call out in the prose the invalidity to aid those that consume "simple grammar + prose" instead of "full grammar"
> (b) briefly explain why the it was excluded from the CSS3 module
> (c) give a perhaps vague hint that it is expected to be supported in a later level of the module, but the meaning/rendering isn't decided upon yet
>
> Both (a) and (c) are simple courtesy to web authors so they avoid wasting their time trying to debug "why doesn't it work?!" with such attempted syntax and builds awareness that this is "undefined space" that might "behave interestingly" in prefixed implementations.
>
> Purpose (b) serves to capture some of the history of the CSS3 grammar both for larger community awareness and as a step towards the CSS4+ grammar discussions.

Fixed.  "Note that percentages are <em>not</em> allowed here; they can
only be used to specify the size of an elliptical gradient, not a
circular one.  This restriction exists because there is no obvious
answer as to which dimension the percentage should be relative to.  A
future level of this module may provide the ability to size circles
with percentages, perhaps with more explicit controls over which
dimension is used."


> # [ ellipse              || [ <length> | <percentage> ]{2} ] [ at <position> ]? , |
>
> 9. Editorial nit:  please fix the 3 space alignment of the position portions for readability.

Ah, sorry about that.  It's aligned "correctly" in the source, but the
use of character escapes meant that the source spacing and the visible
spacing were different.  Fixed.


> # <extent-keyword> = closest-corner | closest-side | farthest-corner | farthest-side
>
> 10. To my recollection, we did not have consensus on the official demise of "cover" and "contain".  Did we resolve on that?  If not, it might be worth adding an issue near "<extent-keyword>" to call that out.

Are you asking for an issue because you disagree, or just for
completeness?  If the latter, I don't think we need to call it out
specially.


> # though negative locations are never directly consulted for rendering
>
> 11. This is incorrect for repeating-radial-gradient.  At least, it is for the way I'm interpreting it.

This is just an interpretation issue, I think.  When the stops are
repeated+shifted for repeating radials, they're no longer at negative
locations.

However, if you have a suggestion for clarification, I'm open to it.


> # Example 18
> # Example 19
> # Example 20
> ...
>
> 12. All radial-gradient examples that contain non-color parameters need to be updated for the new grammar.

Yes, I just didn't have the time yesterday to do this.  Fixed now.


> # &lt;foo>
> # &lt;foo&gt;
>
> 13. Editorial nit:  Can the two Editors tweak their editors so that they agree on what to do with the > character?  The CVSWeb log is a lot more difficult to read than it needs to be.  Real edits are often difficult to find amidst the opposite-direction "fixups" regarding the '>' character.

Sorry about that.  I need to remember to keep the fixups in separate
commits from the content commits.  I'm usually good about it, but the
use of &gt; bothers me.  ^_^

~TJ

Received on Thursday, 1 December 2011 21:16:16 UTC