Skip to content

Commit 5dae7b2

Browse files
committed
[css-highlights-api] Rewrap some text
See https://rhodesmill.org/brandon/2012/one-sentence-per-line/
1 parent 8e0336a commit 5dae7b2

File tree

1 file changed

+24
-14
lines changed

1 file changed

+24
-14
lines changed

css-highlight-api-1/Overview.bs

Lines changed: 24 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -229,16 +229,20 @@ Registering Custom Highlights</h3>
229229
The <dfn>custom highlight name</dfn> assigned to a [=custom highlight=] when it is [=registered=]
230230
is used to identify the highlight during styling (see [[#styling-highlights]]).
231231

232-
Note: When registering a [=custom highlight=], authors are advised to use a
233-
[=custom highlight name=] that is a valid CSS [=identifier=]. Using a name that is not a valid
234-
identifier can make the highlight hard, and in some cases impossible, to style via CSS.
232+
Note: When registering a [=custom highlight=],
233+
authors are advised to use a [=custom highlight name=] that is a valid CSS [=identifier=].
234+
Using a name that is not a valid identifier can make the highlight hard,
235+
and in some cases impossible, to style via CSS.
235236

236237
Note: It is possible to [=register=] a [=custom highlight=] with more than one [=custom highlight name=].
237-
However, using more than one name to style a highlight will assign the highlight multiple different sets
238-
of styles, without a way to control the stacking order of conflicting styles within these sets
239-
during [[#painting|painting]]. This could be limiting for authors and could cause confusing painting behavior
240-
(see the <a href="#styling-problems-with-multiple-names-per-highlight">example</a> below for more context). Therefore,
241-
<b>authors are advised to only use one name per highlight during styling</b>.
238+
However, using more than one name to style a highlight
239+
will assign the highlight multiple different sets of styles,
240+
without a way to control the stacking order of conflicting styles
241+
within these sets during [[#painting|painting]].
242+
This could be limiting for authors and could cause confusing painting behavior
243+
(see the <a href="#styling-problems-with-multiple-names-per-highlight">example</a> below for more context).
244+
Therefore, <b>authors are advised to only use one name per highlight during styling</b>.
245+
242246
<div class=example id=styling-problems-with-multiple-names-per-highlight>
243247
<xmp highlight=html>
244248
<style>
@@ -260,12 +264,18 @@ Registering Custom Highlights</h3>
260264
CSS.highlights.set('bar', h);
261265
</script>
262266
</xmp>
263-
In the example above, the same [=custom highlight=] object is [=registered=] under the names 'foo' and 'bar'.
264-
Since each of the [=style rules=] target the same highlight and have the same [=specificity=], authors might
265-
expect the last rule to win in cascading order and the highlighted content to be green. However, each highlight
266-
name gets an independent set of highlight styles, and the highlight will be painted once per name. In
267-
this case, because 'foo' was registered before 'bar', the highlight will be first painted with 'foo''s
268-
color (green) and then with 'bar''s color (red). As a result, the highlighted content will appear red.
267+
268+
In the example above,
269+
the same [=custom highlight=] object is [=registered=] under the names 'foo' and 'bar'.
270+
Since each of the [=style rules=] target the same highlight and have the same [=specificity=],
271+
authors might expect the last rule to win in cascading order
272+
and the highlighted content to be green.
273+
However, each highlight name gets an independent set of highlight styles,
274+
and the highlight will be painted once per name.
275+
In this case, because 'foo' was registered before 'bar',
276+
the highlight will be first painted with 'foo''s color (green)
277+
and then with 'bar''s color (red).
278+
As a result, the highlighted content will appear red.
269279
</div>
270280

271281
<h2 id=styling-highlights>

0 commit comments

Comments
 (0)