[css-cascade-4] Define aliasing mechanisms. #866.

css-cascade-4/Overview.bs

@@ -283,6 +283,62 @@ Shorthand Properties</h2>
 	Declaring a <a>shorthand</a> property to be ''!important''
 	is equivalent to declaring all of its <a>sub-properties</a> to be ''!important''.
 
+<h3 id="aliasing">
+Aliasing</h3>
+
+	Properties sometimes change names after being supported for a while,
+	such as vendor-prefixed properties being standardized.
+	The original name still needs to be supported for compatibility reasons,
+	but the new name is preferred.
+	To accomplish this, CSS defines two different ways of “aliasing” old syntax to new syntax.
+
+	<dl export>
+		<dt><dfn lt="legacy name alias">legacy name aliases</dfn>
+		<dd>
+			When the old property’s syntax is identical to
+			or a subset of the value space of the new property’s syntax,
+			the two names are aliased with an operation on par with case-mapping:
+			at parse time, the old property is converted into the new property.
+			This conversion also applies in the CSSOM,
+			both for string arguments and property lookups:
+			requests for the old property
+			transparently transfer to the new property instead.
+
+			<div class=example highlight=js>
+				For example, if
+				<css>old-name</css> is a <a>legacy name alias</a> for <css>new-name</css>,
+				<code>getComputedStyle(el).oldName</code>
+				will return the computed style of the <code>newName</code> property,
+				and <code>el.style.setPropertyValue("old-name", "value")</code>
+				will set the <css>new-name</css> property to <code>"value"</code>.
+			</div>
+
+		<dt><dfn lt="legacy shorthand">legacy shorthands</dfn>
+		<dd>
+			When the old property has a distinct syntax from the new property,
+			the two names are aliased using the <a>shorthand</a> mechanism.
+			These shorthands are defined to be <a>legacy shorthands</a>,
+			and their use is <em>deprecated</em>.
+			They otherwise behave exactly as regular shorthands,
+			except that the CSSOM will not use them
+			when serializing declarations. [[CSSOM]]
+
+			<div class=example>
+				For example, the 'page-break-*' properties
+				are <a>legacy shorthands</a> for the 'break-*' properties
+				(see [[css-break-3#page-break-properties]]).
+
+				Setting 'page-break-before: always' expands to 'break-before: page' at parse time,
+				like other shorthands do.
+				Similarly, if 'break-before: page' is set,
+				calling <code>getComputedStyle(el).pageBreakBefore</code> will return <code>"always"</code>.
+				However, when serializing a style block
+				(see [[cssom-1#serializing-css-values]]),
+				the 'page-break-before' property will never be chosen as the shorthand to serialize to,
+				regardless of whether it or 'break-before' was specified;
+				instead, 'break-before' will always be chosen.
+			</div>
+	</dl>
 
 <h3 id="all-shorthand">
 Resetting All Properties: the 'all' property</h3>