Awesome

face-explorer - Library and tools for faces and text properties

Author: Anders Lindgren<br> Version: 0.0.4<br> URL: https://github.com/Lindydancer/face-explorer<br>

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:

• <kbd>RET</kbd> -- 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 <kbd>C-c !</kbd>.

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.

Converted from face-explorer.el by el2markdown.