Suppose that Clon needs to display an option’s description, and that
option belongs to a group. The corresponding face in a theme file would
be the following one:
:face (group :face (items :face (option #| ... |#)))
This face describes how options belonging to a level 1 group are to be
displayed. As such, it is not applicable to toplevel options. When this
face is missing from the theme file, Clon tries to find a more
general one. In that particular case, the theme file might define a
“toplevel” ‘option’ face like this:
:face (option #| ... |#)
This face is more general because it lies at the toplevel. As such, it is considered applicable to toplevel options, but also to options belonging to groups at any level. In the same vein, specifying an ‘option’ face within a ‘group’ face implicitly makes it applicable at any higher group level.
This face reuse mechanism applies to any face in a theme; not
only to the ones used in the examples above. For instance, if you decide
that all headers in Clon’s output should be displayed in the same
way, you can very well specify a ‘header’ face at the toplevel of a
theme file (although Clon never has anything to display in a
‘header’ face at the toplevel), and this face will be used in
synopsis headers, group headers, fallback headers etc..
Now, I must confess that the face reuse mechanism described above was over-simplified. What really happens is not exactly face reuse, but face tree reuse. Here is a more complicated example to clarify things a little.
Suppose Clon needs to display the syntax part of an option that
belongs to a level 1 group. The corresponding face in a theme file would
be the following:
:face (group :face (items :face (option :face (syntax #| ... |#))))
If that face is missing, then Clon will in fact attempt to find a
more general one while preserving as much context as possible. In
other words, the following specifications will be tried, in that order:
:face (items :face (option :face (syntax #| ... |#))) :face (option :face (syntax #| ... |#)) :face (syntax #| ... |#)
I hope this makes sense to you because again, it is the most natural thing to do. What this roughly means is that when you are looking for a way to display an option’s syntax part, you should reuse a more general option’s syntax face first, and only as a very last resort fall back to a ‘syntax’ face specification that would be floating around on its own.