Re: [css3-regions] Editorial comments round 1

Hi Fantasai,

Thanks for your detailed review comments. See my responses below.

I have checked in edits based on this email:

http://dev.w3.org/cvsweb/~checkout~/csswg/css3-regions/Overview.html?rev=1.37;content-type=text%2Fhtml

There are more review comments pending on the mailing list that I still need to incorporate. 

Cheers,
Vincent

On Dec 26, 2011, at 3:22 PM, fantasai wrote:

> These are comments on http://www.w3.org/TR/2011/WD-css3-regions-20111129/
> 
> 2. CSS regions concepts
> -----------------------
> 
> I think section could use some editorial work. I don't have specific
> suggestions, but I do think it could use some reorganization.

[vh] If you do not have suggestions, could you describe what issues you see? That will help me understand and see how to improve it.

> 
> Also, definitions sections are generally normative, not non-normative.

[vh] ok. I thought that normative text had to be made of testable assertions. Some of the text, like the definition of a region, is not testable. So I guess I was working with the wrong assumption?

> 
> 3. Relation to document events
> ------------------------------
> 
> # This section is normative.
> 
> In CSS specs, sections are normative unless otherwise specified. Please
> remove these sentences lest people start to be confused as to whether
> all the rest of our specs are entirely non-normative.

[vh] changed.

> 
> 4.1 The 'flow-into' property
> ----------------------------
> 
> # This note is informative.
> 
> Notes are always informative, so you shouldn't be including this statement.
> Just make sure you start the note with the word "Note". (This word must
> appear directly in the source, as it needs to be present even if CSS is
> disabled. Similarly, examples need to start with some wording that indicates
> the following is an example. See CSS3 Backgrounds and Borders for examples.)

[vh] changed.

> 
> # The 'flow-into' property does not apply to the ::first-line and ::first-character.
> 
> s/::first-character/::first-letter pseudo-elements/

[vh] changed.

> 
> 4.2.1 Auto width on regions
> ---------------------------
> 
> # If a region's ‘width’ property is computed to ‘auto’, its resolved value
> # is computed based on ...
> 
> We usually use either "property computes to" or "property's computed value is".
> 
> "resolved value" is not a CSS term. You want "used value".
> 
> I suggest s/computed/calculated/ for the second instance to avoid confusion
> with "computed value", which is a specific concept in CSS.
> 
> (Yes our terms are confusing. Maybe we should change them. But that should
> be a pan-module discussion; for now, be consistent with CSS 2.1.)

[vh] changed.

> 
> 4.5 The @region rule
> --------------------
> 
> # The ‘@region’ rule consists of the keyword ‘@region’ followed by a selector
> # and a declarations block.
> 
> s/declarations//; This is not block of declarations, it's a block of style rules.

[vh] changed.

> 
> # The region's flow segment selector specifies which range of elements in the
> # flow are subject to the following declaration blocks:
> 
> s/following declaration blocks/style rules in the following block/
> 
[vh] changed.

> # Region styling does not apply to nested regions. If a region ‘A’ receives
> # content from a flow that contains region ‘B’, the content that flows into
> # ‘B’ does not receive the region styling specified for region ‘A’.
> 
> This should be a normative statement, not a note. The second sentence should
> start with the words "For example".

[vh] done.

Received on Tuesday, 24 January 2012 19:57:55 UTC