[css-masking] Editorial: Intro / Interactions / Definitions

https://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html#intro

This paragraph:
   # A mask is applied using the ‘mask’, ‘mask-image’ or ‘mask-box-image’
   # properties. The mask source may be defined using a ‘mask’ element
   # referenced by the ‘mask’ property. Alternatively, for many simple
   # uses, the ‘mask-image’ property may refer directly to graphical
   # elements or images to be used as mask forgoing the need for an
   # explicit ‘mask’ element. The ‘mask’ property is also a shorthand
   # for other masking properties. ‘mask-box-image’ splits a mask image
   # into 9 pieces. The pieces may be sliced, scaled and stretched in
   # various ways to fit the size of the mask image area.

is a rather awkward progression. Maybe start with the simple stuff
and end with the 'mask' shorthand?

https://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html#placement

The intention of this section is mainly to show how the features here
plug into / override other bits of CSS. The first paragraph does a good
job of this.

   # Definitions of CSS properties and values in this specification
   # comply with definitions in CSS Backgrounds and Borders [CSS3BG].

However this paragraph and the table below it imo should shift to
Terminology. Also:
   - "comply with" is kindof weird. UAs comply with specs, but saying
     that css-masking complies with css3-background makes little sense.
     Maybe you mean "are analogous to"?
   - "Every reference will be marked clearly." is unnecessary. I'm glad
     that's your goal, but it doesn't need to be stated here. :)

   # Some property and element definitions in this specification require
   # an SVG 1.1 implementation [SVG11]. UAs without support for SVG [...]

And this paragraph belongs in the Conformance section. Btw, if you
have suggestions for improving the conformance template (like, making
it less awful to read), I would be happy to take them...

https://dvcs.w3.org/hg/FXTF/raw-file/default/masking/index.html#definitions

   I suggest s/Definitions/Terminology/. Most of the spec is defining
   things, yes? :)

   # The term user coordinate system is equivalent to the term local coordinate system.

Would suggest just putting two <dt>s above the "local coordinate system"
definition then.

Your markup is very confused:
   <a class="element-name" href="#MaskElement">‘<code class="property">mask</code>’</a>
Perhaps some other convention than what you're using is needed to distinguish
CSS property names from markup element names? In the CSS specs we tend to
wrap element names in angle brackets instead of quotes, for instance.

~fantasai

Received on Wednesday, 13 March 2013 05:05:43 UTC