[css-logical-1] Editorial rewrite.

Author: fantasai

css-logical-1/Overview.bs

@@ -172,21 +172,33 @@ Value Definitions</h3>
 <h2 id="directional-keywords">
 Flow-Relative Values: <css>block-start</css>, <css>block-end</css>, <css>inline-start</css>, <css>inline-end</css></h2>
 
-  Properties that accept [=physical=] <dfn>directional keyword</dfn> values
-  (<css>top</css>, <css>bottom</css>, <css>left</css>, <css>right</css>)
-  are redefined to also accept the appropriate <a>flow-relative</a> [=directional keywords=]
-  (<css>block-start</css>, <css>block-end</css>, <css>inline-start</css>, <css>inline-end</css>).
-  In such cases,
-  the flow-relative values can be used in place of the corresponding physical values.
-  For properties that take multiple keywords,
-  combinations of flow-relative and physical values are not allowed
-  (unless otherwise specified in a future specification).
+  Many CSS properties have historically accepted <dfn>directional keyword</dfn> values
+  that are [=physical=]
+  (<css>top</css>, <css>bottom</css>, <css>left</css>, <css>right</css>).
+  This specification introduces [=directional keyword=] values that are [=flow-relative=]:
+  <css>block-start</css>, <css>block-end</css>, <css>inline-start</css>, <css>inline-end</css>.
 
-  Properties can be either 1-dimensional or 2-dimensional.
+  A property's effect can be either 1-dimensional or 2-dimensional.
   When contextually constrained to one dimension,
   the flow-relative keywords are abbreviated
   (to <css>start</css> and <css>end</css>).
 
+  CSS Level 2 properties are here redefined to also accept
+  <a>flow-relative</a> directional keywords.
+  Such values can be used in place of the corresponding physical values.
+  For properties that take multiple keywords,
+  combinations of flow-relative and physical values are not allowed
+  (unless otherwise specified in a future specification).
+
+  Note: Newer CSS specifications are expected in most cases to define
+  [=flow-relative=] or [=line-relative=] values
+  instead of or in addition to any [=physical=] ones.
+  In general, the mapping of such relative values are expected to use
+  the [=writing mode=] of the [=containing block=] when affecting the box itself,
+  and that of the box itself when affecting its contents.
+  Regardless, which [=writing modes=] is used for the mapping
+  needs to be explicitly defined.
+
 <h3 id="caption-side">
 Logical Values for the 'caption-side' Property</h3>
 
@@ -294,54 +306,57 @@ Flow-Relative Page Classifications</h2>
 <h2 id="box">
 Flow-Relative Box Model Properties</h2>
 
-  This specification introduces new CSS properties
+  For many formatting effects,
+  the axis or direction affected is encoded in the property name
+  rather than in its value.
+  The type of directional or axis mapping
+  (<a>flow-relative</a> or <a>physical</a>)
+  of each such property
+  is called its <dfn export>mapping logic</dfn>.
+  Historically, all properties have been encoded in [=physical=] terms;
+  this specification introduces new CSS properties
   that are <a>flow-relative</a> equivalents
-  of <a>physical</a> box model properties.
-  Each set of related flow-relative longhand properties
-  and their parallel physical properties,
-  which set equivalent styles on different sides or dimensions of a box,
-  form a <dfn export>logical property group</dfn>.
+  of CSS2’s <a>physical</a> box model properties.
+
+  Note: Newer CSS specifications are expected in most cases to define
+  [=flow-relative=] or [=line-relative=] properties
+  instead of or in addition to any [=physical=] ones.
+
+  Each set of parallel
+  [=flow-relative=] properties and [=physical=] properties
+  (ignoring [=shorthand=] properties)
+  related by setting equivalent styles on the various sides or dimensions of a box,
+  forms a <dfn export>logical property group</dfn>.
   For example, the 'padding-*' properties
   form a single <a>logical property group</a>,
   the 'margin-*' properties
   form a separate <a>logical property group</a>,
   the 'border-*-style' properties
   form another <a>logical property group</a>,
   etc.
-  The type of directional or axis mapping
-  (<a>flow-relative</a> or <a>physical</a>)
-  is called the property’s <dfn export>mapping logic</dfn>.
-
-  Note: Each longhand property is in at most one <a>logical property group</a>.
-
-  The <a>specified values</a> of the <a>flow-relative</a> properties
-  are distinct from
-  the specified values of the parallel physical properties,
-  but the flow-relative and physical properties share computed values.
-  Which pairs of properties share computed values
-  depends on the element’s computed values of
-  'writing-mode', 'direction', and 'text-orientation'.
-
-  Note: Depending on the element’s own <a>writing mode</a>
-  for mapping every <a>flow-relative</a> property
-  to its <a>physical</a> equivalent
-  simplifies the cascading calculations
-  and gives a straightforward model for authors to reason about.
-  However, it is problematic in many cases,
-  see for example <a href="https://www.w3.org/mid/20161108202634.GA7235@mail.internode.on.net">this discussion</a>.
-  Authors may need to use nested elements
-  to get the correct mapping behavior
-  when changing an element’s <a>writing mode</a> from its parent.
-
-  A computed value that has flow-relative and physical properties as input
-  is determined by applying the CSS cascade to declarations of both.
-  Overriding is not determined by whether a declaration is flow-relative or physical,
-  but only by the rules of the CSS cascade [[!css-cascade-3]].
+  (Each [=longhand property=] can belong to at most one <a>logical property group</a>.)
+
+  Within each [=logical property group=],
+  corresponding [=flow-relative=] and [=physical=] properties
+  are paired using the element’s own
+  [=computed value|computed=] [=writing mode=].
+  Although the [=specified value=] of each property remains distinct,
+  paired properties share a [=computed value=],
+  which is determined by [=cascading=]
+  the declarations of both properties together as one;
+  in other words, the [=computed value=] of both properties in the pair
+  is derived from the [=specified=] value of the property declared with
+  higher priority in the CSS [=cascade=]. [[!CSS-CASCADE-3]]
 
   <p class="note">
     Note that this requires implementations to maintain
     relative order of declarations within a CSS declaration block,
     which was not previously required for CSS cascading.
+    It also requires that 'writing-mode', 'direction', and 'text-orientation'
+    be computed as a prerequisite for cascading together
+    the [=flow-relative=] and [=physical=] declarations
+    of a [=logical property group=]
+    to find their [=computed values=].
   </p>
 
   <div class="example">
@@ -371,7 +386,19 @@ Flow-Relative Box Model Properties</h2>
 
   [[!CSSOM]] APIs that return computed values
   (such as <code>getComputedStyle()</code>)
-  must return the same value for equivalent pairs of such properties.
+  must return the same value for each individual property
+  in such a pair.
+
+  Note: Depending on the element’s own <a>writing mode</a>
+  for mapping every <a>flow-relative</a> property
+  to its <a>physical</a> equivalent
+  simplifies the cascading calculations
+  and gives a straightforward model for authors to reason about.
+  However, it is problematic in many cases,
+  see for example <a href="https://www.w3.org/mid/20161108202634.GA7235@mail.internode.on.net">this discussion</a>.
+  Authors may need to use nested elements
+  to get the correct mapping behavior
+  when changing an element’s <a>writing mode</a> from its parent.
 
   ISSUE: There are some open questions on
   the <a href="https://github.com/w3c/csswg-drafts/issues/3029">order of inheritance vs mapping in flow-relative properties</a>