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