In addition to the 10 highlight properties described in the previous
section, Clon
defines 6 layout properties. Here are the first 4 of
them, along with their description and default value.
:visible
¶Whether the face’s contents is visible. Possible values are t
(the
default), or nil
. You can also use the opposite property named
:hidden
. The ‘optlist’ and ‘refcard’ themes make use of
this to avoid printing the options descriptions.
Since the notions of hiding, concealing or making text visible are
somewhat intermixed, Clon
also provides a “bastard” property which,
depending on its value, would be considered either a layout, or a
highlight one. This property is named :display
. Possible values are:
visible
(or revealed
or t
), concealed
and hidden
(or
nil
).
:padding-top
¶The face’s top padding, that is, the number of lines to skip before opening it and displaying its contents. This property can take the following forms.
nil
This face may be opened anywhere, including on the current line. This is the default.
0
This face should be opened on the next line.
<num> (positive)
This face should be opened after skipping <num>
empty lines. Note
that the empty lines are displayed in the enclosing face, not the
face which specifies the top padding.
:padding-bottom
¶This face’s bottom padding, that is, the number of lines to skip before opening the next face and displaying its contents. This property can take the following forms.
nil
The next face may be opened anywhere, including on the current line. This is the default.
0
The next face should be opened on the next line.
<num> (positive)
The next face should be opened after skipping <num>
lines. Note that
the empty lines are displayed in the enclosing face, not the face
which specifies the bottom padding.
:item-separator
¶The face’s item separator, that is, a piece of text to insert between
every sub-face’s contents. The default value is #\space
(a space
character).
The default values above have been chosen because they are convenient for the majority of the faces, but not necessarily all the time. Let us now review some examples of non-default settings in the ‘raw’ theme.
", "
, which in this context is used to separate the short and
long name syntax, as in ‘-h, --help’.
In order to describe the last two layout properties, we need to
introduce the notion of frame first. A frame is a rectangle in
which Clon
prints something. When Clon
opens a face for printing
its contents, it associates a frame with it. Usually, Clon
doesn’t
know the frame’s height because it doesn’t know in advance how many
lines of output will be necessary to display the face’s contents.
However, Clon
usually knows the frame’s width: a frame starts at a
certain column (the left one) and stops at another (the right one).
There is an isomorphic relation between frames and faces: when a face is
a sub-face of a super-face, the corresponding frame is a sub-frame of
the corresponding super-frame. Sub-frames are geometrically enclosed
within their super-frames: a sub-frame can only draw in an equally large
or narrower band than its super-frame. That’s how Clon
handles
vertical alignment of text.
In order to give you control on the starting and ending columns of every frame (in fact, every face), the following two layout properties are defined.
:padding-left
¶A face’s left padding determines its starting column. This property can take the following forms.
<num>
Skip <num>
columns relatively to the enclosing face. The default
value is 0, meaning to open this face at the same column number as the
enclosing one.
(<num> :relative-to <face>)
As above, but relatively to a parent face named <face>
instead of just the enclosing one. This lets you go more than one level
up in the face tree.
(<num> absolute)
Open this face exactly at column <num>
.
self
This face may be opened anywhere, and when it is, its left column is set to the current column number.
:padding-right
¶A face’s right padding, determines its ending column. This property can take the following forms.
<num>
Close this face <num>
columns before the enclosing one.
(<num> :relative-to <face>)
As above, but relatively to a parent face named <face>
instead of just the enclosing one. This lets you go more than one level
up in the face tree.
(<num> absolute)
Close this face exactly at column <num>
.
self
This face may be closed anywhere. This is the default.
The default values above have been chosen because they are convenient for the majority of the faces, but not necessarily all the time. Let us now review some examples of non-default settings in the ‘raw’ theme.
(30 absolute)
which means that the descriptive texts for all options start aligned at
column 30.
There is one important point to understand about self-ending faces (which, again, is the default setting). A self-ending face typically doesn’t know at which column it stops until it stops. In fact, this is not completely true: if the face’s contents needs to span across several lines, then the ending column will be known at the end of the first line, when the ending column of the enclosing face is reached. However, for a piece of contents that fits on a single line, the point holds.
Because of that, it is impossible for a face’s right padding to be relative to a self-ending face. This would be like saying “stop 2 columns before I don’t know where”. Here are two examples of such invalid settings (an error will be thrown if you try that in a theme):
:face (option :face (syntax :padding-right 2)) :face (option :face (syntax :face (short :padding-right (2 :relative-to option))))