Homepage: https://github.com/Lindydancer/face-explorer
Author: Anders Lindgren
Updated:
Library and tools for faces and text properties
Library and tools for faces and text properties.
This library is useful for packages that convert syntax highlighted
buffers to other formats. The functions can be used to determine
how a face or a face text property looks, in terms of primitive
face attributes (e.g. foreground and background colors). Two sets
of functions are provided, one for existing frames and one for
fictitious displays, like 8 color tty.
In addition, the following tools are provided:
- `face-explorer-list-faces' -- list all available faces. Like
`list-faces-display' but with information on how a face is
defined. In addition, a sample for the selected frame and for a
fictitious display is shown.
- `face-explorer-describe-face' -- Print detailed information on
how a face is defined, and list all underlying definitions.
- `face-explorer-describe-face-prop' -- Describe the `face' text
property at the point in terms of primitive face attributes.
Also show how it would look on a fictitious display.
- `face-explorer-list-display-features' -- Show which features a
display supports. Most graphical displays support all, or most,
features. However, many tty:s don't support, for example,
strike-through. Using specially constructed faces, the resulting
buffer will render differently in different displays, e.g. a
graphical frame and a tty connected using `emacsclient -nw'.
- `face-explorer-list-face-prop-examples' -- Show a buffer with an
assortment of `face' text properties. A sample text is shown in
four variants: Native, a manually maintained reference vector,
the result of `face-explorer-face-prop-attributes' and
`face-explorer-face-prop-attributes-for-fictitious-display'. Any
package that convert a buffer to another format (like HTML, ANSI,
or LaTeX) could use this buffer to ensure that everything work as
intended.
- `face-explorer-list-overlay-examples' -- Show a buffer with a
number of examples of overlays, some are mixed with `face' text
properties. Any package that convert a buffer to another format
(like HTML, ANSI, or LaTeX) could use this buffer to ensure that
everything work as intended.
- `face-explorer-tooltip-mode' -- Minor mode that shows tooltips
containing text properties and overlays at the mouse pointer.
- `face-explorer-simulate-display-mode' -- Minor mode for make a
buffer look like it would on a fictitious display. Using this
you can, for example, see how a theme would look in using dark or
light background, a 8 color tty, or on a grayscale graphical
monitor.
Fictitious displays:
Emacs supports a variety of displays, from graphical frames to
terminals with 8 colors. Emacs itself provides query functions for
existing displays. This library provides query functions for any
kind of display, allowing you to play the "what if" game. (For
example, how would a face look on a grayscale graphical display or
an 8 color tty.)
It is possible to use the query functions for fictitious displays
in batch mode, when the normal face and colors system are severely
restricted.
Library functions:
Function for existing frames:
- `face-explorer-face-attributes' -- The face attributes
of a face, after expanding all inherited faces.
- `face-explorer-face-prop-attributes' -- The primitive face
attributes of a face specification, as used by the `face' text
property. Effectively, this can tell how a piece of text look to
the user, expressed in terms of foreground color, background
color, underline etc. Face remappings performed by
`face-remapping-alist' are handled.
- `face-explorer-face-attributes-at' -- The primitive face
attributes at a specific position in a buffer.
Support for a fictitious display:
The following variables defines a fictitious display. The
face-explorer tools use the global variants of these variables.
However, when calling the functions in the library, it's possible
to dynamically bind them using `let'.
- `face-explorer-number-of-colors' -- Number of colors.
- `face-explorer-background-mode' -- The background mode, either
`light' or `dark'.
- `face-explorer-color-class' -- The color class: `color',
`grayscale', or `mono'.
- `face-explorer-window-system-type' -- The window system type,
either a symbol like `tty' or a list like `(graphic ns)'.
- `face-explorer-match-supports-function' -- A function to call to
determine the features a display supports. By default, a
graphical display supports everything and a tty supports things
like underline and inverse video.
The following functions can be used to query face-related
information for fictitious displays:
- `face-explorer-face-attributes-for-fictitious-display'
-- The face attributes of a face, after expanding all inherited
faces, for a fictitious display.
- `face-explorer-face-prop-attributes-for-fictitious-display' --
The primitive face attributes of a face specification, as used by
the `face' text property, for a fictitious display. Effectively,
this can tell how a piece of text look to the user, expressed in
terms of foreground color, background color, underline etc.
- `face-explorer-face-attributes-for-fictitious-display-at' -- The
primitive face attributes at a specific position in a buffer, for
a fictitious display.
Face-related tools:
This package provide a number of face-related tools. Most of them
display information about a face both in the selected frame and as
it would look on a fictitious display.
Key bindings:
In the tool buffers, you can use the following keys to change the
settings:
- `-', `+', and `#' -- Decrease, increase, and set the number of
colors of the fictitious display. The increase and decrease
commands use 8, 16, 256, and "infinite" colors.
- `b' -- Toggle between light and dark background mode.
- `c' -- Step to the next color class.
- `r' -- Reset the fictitious display to match the selected frame.
- `g' -- Toggle the window system between that of the selected frame
and a terminal.
Face verifiers:
The `face-explorer-list-faces' and `face-explorer-describe-face'
tools warn about inappropriately defined faces. You can use the
following keys to handle these warnings:
- `wd' -- Disable verifier
- `we' -- Enable verifier
- `wa' -- Enable all verifiers
- `wn' -- Disable all verifiers
- `wx' -- Describe verifier.
The `face-explorer-list-faces' tool:
List all available faces. Like `list-faces-display' but with
information on how a face is defined. In addition, a sample for
the both the selected frame and for the current fictitious display
is shown.
Additional keys:
- `RET' -- Open the `face-explorer-describe-face' tool for the face
on the line of the cursor.
The `face-explorer-describe-face' tool:
Display information about a face. This includes:
- The documentation
- The face attributes in the selected frame
- Ditto, but with inheritances resolved
- Primitive face attributes and samples for the current fictitious display
- Samples for a number of typical fictitious displays
- The face specifications used to define the face, originating from
`defface', `custom-theme-set-faces' etc.
The `face-explorer-describe-face-prop' tool:
Display information about a `face' text property. This includes:
- The value of the property
- The corresponding primitive face attributes in the selected frame,
with samples.
- Ditto for the current fictitious display
- Samples how the `face' text property would look in a number of
typical fictitious displays.
The `face-explorer-list-display-features' tool:
Display a buffer contains text using specially constructed faces
that will look differently depending on available display features.
For example, if you run `emacsclient -nw' from a terminal, this
buffer will look differently than it does in a graphical frame.
The `face-explorer-list-face-prop-examples' tool:
List sample text with face text properties in various variants.
This is useful for two reasons:
- It can be used to investigate how Emacs, rally, displays various
faces and text properties.
- It can be used to test packages that convert text with text
properties to various other format, like PostScript, HTML, ANSI,
LaTeX etc.
The `face-explorer-list-overlay-examples' tool:
List sample text with overlays in various variants.
The `face-explorer-tooltip-mode' tool:
A minor mode that shows information about text
properties and overlays in a tooltip.
This is enabled in all buffers displayed by the tools in this
module.
`face-explorer-tooltip-global-mode' can be used to enable this mode
for all buffers.
The `face-explorer-simulate-display-mode' tool:
A minor mode used to show how the current buffer would look in a
fictitious display. This can be used, for example, to check if a
face theme would look good in a 8 color tty or in a grayscale
graphical display.
The key bindings describe above above are available after the
prefix `C-c !'.
Note: The mode will not restrict colors to the fictitious display.
For example, if a face is defined as "red" it will be shown in red
even when the fictitious display is set to `mono' or `grayscale'.
`face-explorer-simulate-display-global-mode' can be used to enable
this mode for all buffers.
Vocabulary:
Primitive face attributes:
Normally, a face or face specification can be quite complex, for
example a face can inherit from other faces and a face
specification can contain several faces. "Primitive face
attributes" corresponds to how the face or face specification will
look to the user, the foreground and background color it has,
whether it is bold or italic etc. Unspecified properties are not
included. Properties like :height could be relative (like 1.2) or
absolute (like 10). Primitive face attributes never contain the
`:inherit' attribute.
Technical background:
Face definitions:
The attributes associated with a face can originate from the
following locations:
- `defface' -- This construct defines a customizable face. The
information is stored in the property `face-default-spec' in the
face symbol. Normally it is accessed using the function
`face-default-spec'.
- Customize -- A user can customize a face using
`custom-theme-set-faces'. The `theme-face' property of the face
symbol contains an alist from active themes to display
requirements face specifications.
- Overrides -- Face attributes can be overridden using the function
`face-spec-set'. This information is stored in the
`face-override-spec' property in the face symbol.
- Future frames -- The function `set-face-attribute' can specify
that an attribute should be set for future frames, by passing nil
or `t' as FRAME. This information can be accessed using
`face-attribute' by passing `t' as the FRAME.
- Existing frames -- A face attribute can be changed in existing
frames by `set-face-attribute' by passing a frame or nil as
FRAME. This information can be accessed using `face-attribute'.
Face aliases:
The `face-alias' property of the face symbol can contain another
symbol which the face is aliased to.
Distant foreground:
A "distant foreground" is an alternative color used to render the
foreground when the normal foreground color would be too close to
the background. Unfortunately, there is no clear definition of
what "too close" really means, so it is hard to simulate it.
Currently, this package return both the `:foreground' and
`:distant-foreground' attributes. Hopefully, in the future, it
might be possible to deduce the color that is shown and use
`:foreground' to represent that color.
Other Font Lock Tools:
This package is part of a suite of font-lock tools. The other
tools in the suite are:
Font Lock Studio:
Interactive debugger for font-lock keywords (Emacs syntax
highlighting rules).
Font Lock Studio lets you *single-step* Font Lock keywords --
matchers, highlights, and anchored rules, so that you can see what
happens when a buffer is fontified. You can set *breakpoints* on
or inside rules and *run* until one has been hit. When inside a
rule, matches are *visualized* using a palette of background
colors. The *explainer* can describe a rule in plain-text English.
Tight integration with *Edebug* allows you to step into Lisp
expressions that are part of the Font Lock keywords.
Font Lock Profiler:
A profiler for font-lock keywords. This package measures time and
counts the number of times each part of a font-lock keyword is
used. For matchers, it counts the total number and the number of
successful matches.
The result is presented in table that can be sorted by count or
time. The table can be expanded to include each part of the
font-lock keyword.
In addition, this package can generate a log of all font-lock
events. This can be used to verify font-lock implementations,
concretely, this is used for back-to-back tests of the real
font-lock engine and Font Lock Studio, an interactive debugger for
font-lock keywords.
Highlight Refontification:
Minor mode that visualizes how font-lock refontifies a buffer.
This is useful when developing or debugging font-lock keywords,
especially for keywords that span multiple lines.
The background of the buffer is painted in a rainbow of colors,
where each band in the rainbow represent a region of the buffer
that has been refontified. When the buffer is modified, the
rainbow is updated.
Faceup:
Emacs is capable of highlighting buffers based on language-specific
`font-lock' rules. This package makes it possible to perform
regression test for packages that provide font-lock rules.
The underlying idea is to convert text with highlights ("faces")
into a plain text representation using the Faceup markup
language. This language is semi-human readable, for example:
«k:this» is a keyword
By comparing the current highlight with a highlight performed with
stable versions of a package, it's possible to automatically find
problems that otherwise would have been hard to spot.
This package is designed to be used in conjunction with Ert, the
standard Emacs regression test system.
The Faceup markup language is a generic markup language, regression
testing is merely one way to use it.
Font Lock Regression Suite:
A collection of example source files for a large number of
programming languages, with ERT tests to ensure that syntax
highlighting does not accidentally change.
For each source file, font-lock reference files are provided for
various Emacs versions. The reference files contains a plain-text
representation of source file with syntax highlighting, using the
format "faceup".
Of course, the collection source file can be used for other kinds
of testing, not limited to font-lock regression testing.
History:
Part of the code of this package was originally published as part
of the package `e2ansi', a package that can emit highlighted text
to a terminal using ANSI sequences. `e2ansi' can be configured to
be used with the command line command `more' and `less' to syntax
highlight anything viewed using those command.