W3C home > Mailing lists > Public > www-style@w3.org > August 2009

[css3-background] bg-position syntax clarification

From: Tab Atkins Jr. <jackalmage@gmail.com>
Date: Sat, 22 Aug 2009 12:16:39 -0500
Message-ID: <dd0fbad0908221016j3b9437cn54180469469c681b@mail.gmail.com>
To: www-style list <www-style@w3.org>
The gradient discussion has revealed that many people (me included)
simply do not have a good grasp of what the syntax for a <bg-position>
really means, beyond the most basic examples with two keywords or two
offsets.  I don't believe this is any true fault of the syntax, but
rather simply a failure in the explanation.  I think the explanation
in the Backgrounds and Borders module is geared toward helping
developers parse the value (thus the constant references to "if x
values are specified...") rather than helping authors write the value.
 I have tried to write a more clarifying explanation of the syntax
below, with a holistic focus starting from the full syntax and
explaining what happens when certain things are omitted:


<bg-position>:
  <horizontal-component> || <vertical-component>

<horizontal-component>:
  [ [ left | right ]? <offset>? ] | center

<vertical-component>:
  [ [ top | bottom ]? <offset>? ] | center

<offset>:
  <length> | <percentage>

A bg-position is defined by two components, a horizontal and a
vertical.  Each specifies a side and an offset from that side.
Positive offsets indicate a direction into the box, negative offsets
point outside of the box.  For example, "right 10px top 20px"
specifies a point 10px to the left of the right edge, and 20px down
from the top edge.

Generally, the horizontal component must be specified first, followed
by the vertical component.  You are allowed to swap these if and only
if both components have their side specified.  As well, as specified
in the grammar above, the side (if present) must be specified before
the offset (if present).

If an offset is omitted from a component but the side is specified,
the offset defaults to '0'.

If the horizontal component's side is omitted but the offset is
specified, the side default to 'left'.  If the vertical component's
side is omitted but the offset is specified, the side defaults to
'top'.

Either component can be replaced by 'center'.  This is exactly
equivalent to omitting the side and specifying '50%' as the offset,
and is subject to the normal rules and restrictions that are applied
when you omit the side from a component.

An entire component can be omitted only under particular
circumstances, as this introduces the potential for ambiguity.  The
horizontal component can be omitted (and defaults to 'center') if and
only if the vertical component's side is specified (the vertical
offset may be omitted).  The vertical component can be omitted (and
defaults to 'center') if and only if the horizontal side *or* the
horizontal offset is omitted; you cannot omit the vertical component
if you specify both parts of the horizontal component.



I've obviously played a little loose with the language; the phrase
"background positioning area" doesn't appear anywhere in my prose.  It
can be easily patched up to be more precise.  As well, further
clarifications such as what exactly percentage values for offsets mean
are already adequately explained in the B&B module, so I've left them
out here.

My specification actually breaks from the one given in B&B in one
place: if three values are specified, my syntax allows them to be a
side and two offsets, while B&B requires them to be either two sides
and an offset or a side, an offset, and 'center'.  That is, "left 10px
20px" is allowed in my syntax and expands to "left 10px top 20px", but
it is not allowed in the current B&B syntax.  Is this acceptable?  I
think that this case is pretty easy to parse, and it would complicate
the explanation to disallow it ("left 10px 50%" is at least no harder
than "left 10px center", which it should be equivalent to.).  I
suspect that the only reason it's not allowed currently is precisely
because it's more difficult to explain it in the current style;
disallowing it actually simplifies the current language.  In my
language it's very simple - you've just omitted one of the values, and
it's very clear what effect that has.

Thoughts?  Improvements?  Does this actually help people understand
the complex syntax of bg-position?  I expect this syntax to be reused
many times in the future, as it's very useful, and want it to be as
accessible as possible.

~TJ
Received on Saturday, 22 August 2009 17:17:35 GMT

This archive was generated by hypermail 2.3.1 : Tuesday, 26 March 2013 17:20:20 GMT