Re: slight critice of the shorthands' value descriptions

On Tue, 16 Jan 2018 12:26:19 -0800
fantasai <fantasai.lists@inkedblade.net> wrote:

> 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.

What about always putting the shorthand first. If that is deprecated
or not assembling all longhand values, this only needs one explanatory
paragraph just right at place (maybe right below the title).

> > 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
> 
> 


Regards,
---------------------------------------------------------------------
Dennis Heuer
einz@verschwendbare-verweise.seinswende.de

Received on Tuesday, 16 January 2018 23:24:49 UTC