Re: slight critice of the shorthands' value descriptions

On 01/15/2018 05:37 PM, Dennis Heuer wrote:
> On Mon, 15 Jan 2018 14:30:20 -0800
> fantasai <fantasai.lists@inkedblade.net> wrote:
> 
>> On 01/13/2018 10:22 AM, Dennis Heuer wrote:
>>> Hello again,
>>>
>>> please, could you generally try to list the shorthands' values
>>> in order of the descriptions of the longhands in the documents
>>
>> I'm sorry, I don't quite understand your comment. Could you give
>> an example, please?
> 
> Shure, I wrote this at an early point where I read the spec for the
> text-decoration. The individual specs treat this rather chaotically,
> also for values. Sometimes the shorthand is specified first and then
> come the individual properties. Most often the shorthand is specified
> after the individual properties.

Yes... there is an inconsistency there. Most of the time we describe the
longhands first, but there are some exceptions:

   * In some cases, the longhands are discouraged. (This is the case for
     the 'flex' property.) For these we describe the shorthand first, to
     encourage readers to think in terms of the shorthand (and to skip
     reading the longhands if they find what they are looking for in this
     section.) https://www.w3.org/TR/css-flexbox-1/#flexibility

   * In other cases, describing the longhands first would be distracting
     because there are too many of them and the shorthand encompasses the
     concept more plainly. This is the case for the 'scroll-margin' and
     'scroll-padding' properties: it's easy to understand what they do
     just from the shorthand, and listing the 8 longhands (one per side
     per coordinate system) would get in the way of understanding the
     fundamental concept of the property. So we relegated these to an
     appendix. https://www.w3.org/TR/css-scroll-snap-1/#scroll-padding

So, basically, we optimized for readability rather than consistency in
choosing the order of presenting shorthand vs. longhand in the spec prose.

> In both cases the order in which the
> individual properties follow in the spec is not same like the order in
> which the individual properties are refered to in the specification of
> the shorthand, i.e.:
> 
> Name:  text-decoration
> Value:  <text-decoration-line>  ||
>          <text-decoration-style> ||
>          <text-decoration-color>
> 
> The order in the document is:
> 
> text-decoration-line
> text-decoration-color
> text-decoration-style
> text-decoration
> 
> Here I'd prefer to specify color after style because I find this more
> logical. In other words, the shorthand does it right!

OK, I've updated CSS Text Decoration Level 3 to describe -style before -color,
as you suggest. :) I'll try to keep in mind to cross-check this as I work, but
if you find any other cases where the order is swapped, let me know and I will
fix them (or ask the editor to fix them, if I am not the editor of that spec).

~fantasai

Received on Tuesday, 16 January 2018 20:27:46 UTC