[css-shapes] comments on new shapes syntax spec

   # <shape-radius> = <length> | <percentage> | closest-side
   # | farthest-side | contain
   # Defines a radius for a circle or ellipse. If omitted it
   # defaults to contain.
   #   closest-side uses the length from the center of the
   #     shape to the closest side of the relevant box.
   #   farthest-side uses the length from the center of the
   #     shape to the farthest side of the relevant box.
   #   contain uses the same value as closest-side for circle().
   #     For ellipse the rx value uses the length from the
   #     center of the shape to the closest width side, and the
   #     ry value uses the length from the center of the shape
   #     to the closest height side.

Since radial gradients don't have a 'contain' keyword, I suggest
that we don't have 'contain' here either. It is equivalent to
closest-side.

However, closest-side and farthest-side should be clarified for
ellipses so that they're restricted to the dimension they're
assigned to, and for circle should be clarified that they find
the specified distance in any direction.

  # circle() = circle( [<shape-radius>] [at <position>] )
  # ellipse() = ellipse( [<shape-radius>{1,2}] [at <position>] )

These don't correctly express the optionality of the position:
missing ? from the grammar.

====== random editorial bits ======

  # relevant box

I would suggest s/relevant box/reference box/g;

Also, this should be marked up as a term: it should get a <dfn>
somewhere in a statement defining what it means, and wrapped in
<i> or <a> throughout so it cross-links.

  # The coordinate system for the shape has its origin on the
  # top-left corner of the relevant box with the x-axis running
  # to the right and the y-axis running downwards.

Since this sentence is now only needed for polygons, it should
go in the definition of polygon(), not in the intro paragraph.

  #  For the radius r of a circle(), a percentage value is resolved
  # from the used width and height of the relevant box as
  # sqrt((width)**2 + (height)**2))/sqrt(2).

I'm wondering if this sentence should likewise go in the definition
of circle() rather than in the intro paragraph.

  # The type is defined in [CSS3VAL]

You can remove this sentence, it's covered by the boilerplate in
   http://dev.w3.org/csswg/css-shapes/#values
(which is why we have that boilerplate). Since <position> is also
hyperlinked, it's really unnecessary imo to have the extra reference.

However, you might want to drop a [CSS3VAL] link at the end of
this sentence: "All <basic-shape> values use functional notation
and are defined here using the Value Definition Syntax."

  # Possible values are nonzero or evenodd. Default value when
  # omitted is nonzero.

Use double single quotes ''nonzero'' around keywords. :)

  # <fill-rule> = nonzero | evenodd

I think you can inline this definition into the first bullet of
polygon()'s definition.

  # The following shapes are supported. [...]
  # <shape-arg> = <length> | <percentage>

The structure you're using here implies that <shape-arg>, as
a member of the same list as circle() etc., is also a shape.

~fantasai

Received on Monday, 11 November 2013 16:34:19 UTC