1. Introduction

Text is easier to read when it is accompanied with styling information, such as color, font attributes (weight, posture), or underlining, and this styling is customized appropriately for the output device.

GNU libtextstyle provides an easy way to add styling to programs that produce output to a console or terminal emulator window. It does this in a way that allows the end user to customize the styling using the industry standard, namely Cascading Style Sheets (CSS).

1.1 Style definitions

Let's look at the traditional way styling is done for specific programs.

Browsers, when they render HTML, use CSS styling.

The older approach to user-customizable text styling is that the user associates patterns with escape sequences in an environment variable or a command-line argument. This is the approach used, for example, by the GNU ‘ls’ program in combination with the ‘dircolors’ program. The processing is distributed across several steps:

1. There is default style definition that is hard-coded in the ‘dircolors’ program. The user can also define their own definitions in a file such as ‘~/.dir_colors’. This style definition contains explicit terminal escape sequences; thus, it can only be used with consoles and terminal emulators, and each style definition applies only to a certain class of mostly-compatible terminal emulators.
2. The dircolors program, when invoked, translates such a style definition to a sequence of shell statements that sets an environment variable LS_COLORS.
3. The shell executes these statements, and thus sets the environment variable LS_COLORS.
4. The program looks at the environment variable and emits the listed escape sequences.

In contrast, this library implements styling as follows:

1. There is a default style definition in a CSS file that is part of the same package as the stylable program. The user can also define their own definitions in a CSS file, and set an environment environment variable to point to it.
2. The program looks at the environment variable, parses the CSS file, translates the styling specifications to the form that is appropriate for the output device (escape sequences for terminal emulators, inline CSS and <span> elements for HTML output), and emits it.

Thus, with GNU libtextstyle, the styling has the following properties:

• It is easier for the user to define their own styling, because the file format is standardized and supported by numerous syntax aware editors.
• A styling file does not depend on the particular output device. An HTML output and a black-on-white terminal emulator can use the same styling file. A white-on-black (or even green-on-black) terminal emulator will need different styling, though.
• It is simpler: There is no need for a program that converts the style specification from one format to another.

1.2 Built-in versus separate styling

There are generally two approaches for adding styling to text:

• The program that generates the text adds the styling. It does so through interleaved statements that turn on or off specific attributes.
• The styling gets added by a separate program, that postprocesses the output. This separate program usually uses regular expressions to determine which text regions to style with a certain set of text attributes.

The first approach produces a styling that is 100% correct, regardless of the complexity of the text that is being output. This is the preferred approach for example for JSON, XML, or programming language text.

The second approach works well if the output has a simple, easy-to-parse format. It may produce wrong styling in some cases when the text format is more complex. This approach is often used for viewing log files.

GNU libtextstyle supports both approaches; it includes an example program for each of the two approaches.

This document was generated by dpb build user on December, 4 2024 using texi2html 1.78a.