Discussion:
slight critice of the shorthands' value descriptions
(too old to reply)
Dennis Heuer
2018-01-13 18:22:57 UTC
Permalink
Raw Message
Hello again,

please, could you generally try to list the shorthands' values
in order of the descriptions of the longhands in the documents

Many thanks,
---------------------------------------------------------------------
Dennis Heuer
***@verschwendbare-verweise.seinswende.de
Dennis Heuer
2018-01-16 01:37:11 UTC
Permalink
Raw Message
On Mon, 15 Jan 2018 14:30:20 -0800
Post by Dennis Heuer
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?
~fantasai
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. 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!

Regards,
---------------------------------------------------------------------
Dennis Heuer
***@verschwendbare-verweise.seinswende.de
fantasai
2018-01-16 20:26:19 UTC
Permalink
Raw Message
Post by Dennis Heuer
On Mon, 15 Jan 2018 14:30:20 -0800
Post by Dennis Heuer
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.
Post by Dennis Heuer
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
Name: text-decoration
Value: <text-decoration-line> ||
<text-decoration-style> ||
<text-decoration-color>
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
Dennis Heuer
2018-01-16 22:41:34 UTC
Permalink
Raw Message
On Tue, 16 Jan 2018 12:26:19 -0800
Post by fantasai
Post by Dennis Heuer
On Mon, 15 Jan 2018 14:30:20 -0800
Post by Dennis Heuer
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
* 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).
Post by fantasai
Post by Dennis Heuer
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
Name: text-decoration
Value: <text-decoration-line> ||
<text-decoration-style> ||
<text-decoration-color>
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
***@verschwendbare-verweise.seinswende.de

Loading...