[css-shapes] Minor Comments

1.3 Definitions

   # Line boxes next to a float are shortened as necessary
   # to avoid intersections with the float area.

This seems to imply that this is the only impact of floats on
nearby content; however that's not true, because BFC roots are
also affected. Perhaps it would be better to introduce this
effect as an example, and point at the relevant CSS2.1 section?

2. Shapes

   # Shapes define arbitrary geometric contours around which
   # inline content flows.

This seems like an overly-broad definition of the word "shape".
Also, we're talking about more than just inline content here,
see BFC comment above. I suggest merging the useful comments
here into the introduction instead of having this section.

Overall the document structure needs a little bit of flattening,
probably due to being split out from Exclusions. The entire spec
now is about Shapes. Putting all of its normative content into
a chapter called Shapes is a little redundant, no? :)

2.1. Relation to the box model and float behavior

   # While the boundaries used for wrapping inline flow content
   # outside a float can be defined using shapes, the actual box
   # model does not change. If the element has specified margins,
   # borders or padding they will be computed and rendered
   # according to the [CSS3BOX] module.

I'd clarify that shapes also do not affect the float's position.

(I'd ask what would happen if shape-outside increases the float's
area, but that's apparently impossible. Good to keep in mind that
it could be complicated if we ever try, though!)

   # A shape-outside can create open areas on both the left and
   # right of a float area. Content still wraps only on one side
   # of a float in this case.

This needs to be stated normatively.

2.2. Basic Shapes

   # Shapes can be specified using syntax similar to SVG's basic
   # shapes.

I'm having trouble seeing how CSS's syntax is in any way similar
to <rect x=... y=... width=... height=.../> etc. Am I missing
something?

   # For the radius r of the circle shape, a percentage value is
   # resolved as specified in the SVG recommendation [SVG11].

The most relevant thing I can find in the linked section of SVG
is this sentence:

   # For any other length value expressed as a percentage of the
   # viewport, the percentage is calculated as the specified
   # percentage of
   #   sqrt((actual-width)**2 + (actual-height)**2))/sqrt(2).

which is not actually relevant because our percentages here are
not percentages of the viewport... so unless I'm missing the
the true relevant sentence in the SVG spec, please inline the
appropriate definition here... and if not, please inline it
anyway, because it's not immediately obvious. :)

2.2.1. Supported Shapes

   # The values for corner radii on rectangle or inset-rectangle
   # are determined implicitly if either the rx or ry arguments
   # are not specified, or are specified but with invalid values.

If there are invalid values, the declaration should be invalid
and ignored, as with any other CSS syntax. As for the case of
being not specified... what does "determined implicitly" mean?

   # The shape is extracted and computed based on the alpha
   # channel of the specified <image> [CSS3VAL] User agents must

Suggest

   | The shape is extracted and computed based on the alpha
   | channel of the specified <image> *as defined by
   |' shape-image-threshold'*.
   |
   | User agents must [...]

Added: - reference to shape-image-threshold
        - missing period
        - paragraph break to separate UA network gunk from
          the author-relevant parts of the description.

1.2 Values

   # CSS Values and Units Module Level 3 [[!CSS3VAL].

Missing close-bracket. You should remove all other references
to CSS3VAL from the document: this section is up front so that
they are not necessary every time you mention a new type.

2.4.2. The ‘shape-image-threshold’ Property

   # Value: <threshold>

s/threshold/number/
s/A <number> value that //

Don't define new types just to have nice names for things. Only
define new types if you have something too complex to express
in the propdef table. Inlining the real value makes it easier
to figure out what the property takes, and is especially useful
in index tables and the like.

***

Overall, you're missing a lot of markup. If you're using Bert's
preprocessor you should be using
   'property-name'
   ''value''
   ''function()''
   <var>&lt;type></var>
to facilitate cross-linking. If you're using Tab's, see his
documentation; but these four types of things should be marked
up everywhere they occur.

~fantasai

Received on Tuesday, 1 October 2013 06:57:28 UTC