4.4.1 Theme Elements

Hear hear! If you understand what M-x all-hail-[x]emacs means, you’re going to get quite comfy here. Clon themes are articulated around two basic concepts: faces and (face) properties. A property describes some visual attribute for some piece of text, for instance bold, red, indented by 2 columns to the right. A face is more or less a set of properties (but there’s more to it than that; please hold your post). Every piece of text in Clon’s output is associated with a face, which in turn defines specific values for specific properties.

There are two property types in Clon: highlight properties, which describe the visual appearance of characters (color, font etc.), and layout properties, which describe the text geometry (line width, indentation etc.). Please see Highlight Properties and Layout Properties for an exhaustive list of them.

Let’s have a look at a very simple theme file now.

;; A very simple theme file.

:background black
;; ...

:face (synopsis :foreground red
                ;; ...
                :face (header :bold t #| ...|#)
                #| ... |#)
;; ...

The first line is a comment. Comments begin with a semi-colon and extend to the end of the line. There is another syntax for comments, as show later in the file: a comment can be opened with ‘#|’ and closed with ‘|#’. This form allows you to create comments that span across several lines, or just part of a single line.³

The next line sets the ‘background’ property to ‘black’. It means that Clon’s output will be displayed over a black background (no kidding). Every property in Clon has a name, which you specify by using a keyword (i.e. the name prepended with a colon). But wait, properties are supposed to belong to faces, right? So what is that property doing, floating around like that in the file? That’s right, clever. In fact, the whole output of Clon is wrapped in a global face called ‘toplevel’. You will never need to mention this face explicitly, though, because the contents of theme files is always enclosed in that face.

Later in the file, you find yourself contemplating a face specification. Faces are specified by using the keyword ‘:face’. What follows is a list beginning with the face name, and continuing with property specifications. In this particular example, we’re specifying that the synopsis line (the one that says “Usage: blah blah”) should appear in red, although as you can see, the story does not stop there.

Indeed, there is also a ‘header’ face specification within the ‘synopsis’ one. What it says it that the header part (the “Usage:” portion of the synopsis line) should additionally be displayed in bold font. So it turns out that face specifications can be nested. In fact, all the faces you specify are sub-faces of the ‘toplevel’ face at some level. In this example, the ‘header’ face is a sub-face of the ‘synopsis’ one. This is important for two reasons:

1. face nesting leads to the notion of property inheritance (see Highlight Inheritance),
2. Clon makes use of faces with the same name in different (nesting) contexts. For instance, there are many places where the ‘header’ face is used (see Faces), but this face can have very different specifications according to where it appears in a face tree.