Face Tree Reuse

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.