2. The end user's perspective

Styled output can viewed fine in a console or terminal emulator window.

The stylable program will typically have the following options:

--color

Use colors and other text attributes always.

--color=when

Use colors and other text attributes if when. when may be always, never, auto, or html.

--style=style-file

Specify the CSS style rule file for --color.

For more details, see the sections The --color option and The --style option below.

If the output does not fit on a screen, you can use ‘less -R’ to scroll around in the styled output. For example:

program --color arguments | less -R

2.1 The environment variable TERM

The environment variable TERM contains a identifier for the text window's capabilities. You can get a detailed list of these cababilities by using the ‘infocmp’ command (for example: infocmp -L1 xterm), using ‘man 5 terminfo’ as a reference.

When producing text with embedded color directives, a libtextstyle-enabled program looks at the TERM variable. Text windows today typically support at least 8 colors. Often, however, the text window supports 16 or more colors, even though the TERM variable is set to a identifier denoting only 8 supported colors. It can be worth setting the TERM variable to a different value in these cases.

After setting TERM, you can verify how well it works by invoking ‘program --color=test’, where program is any libtextstyle-enabled program, and seeing whether the output looks like a reasonable color map.

2.1.1 Terminal emulator programs

The following terminal emulator programs support 256 colors and set TERM=xterm-256color accordingly:

• In GNOME: gnome-terminal, tilda.
• rxvt-unicode (sets TERM=rxvt-unicode-256color).
• st (sets TERM=st-256color).
• QTerminal.
• On macOS: Terminal, iTerm2.

The following terminal emulator programs support 256 colors. You only need to set TERM=xterm-256color or similar; the programs by default set TERM to a value that supports only 8 colors.

• xterm is in many cases built with support for 256 colors. But it sets TERM=xterm. You need to set TERM=xterm-256color.
• In GNOME: guake (sets TERM=xterm). You need to set TERM=xterm-256color.
• In KDE: konsole (sets TERM=xterm). You need to set TERM=xterm-256color or TERM=konsole-256color.
• In KDE: yakuake (sets TERM=xterm). You need to set TERM=xterm-256color.
• In Enlightenment: Eterm (sets TERM=Eterm). You need to set TERM=Eterm-256color.
• mlterm (sets TERM=mlterm). You need to set TERM=mlterm-256color.
• On Windows: PuTTY (sets TERM=xterm). You need to set TERM=xterm-256color or TERM=putty-256color.
• On Windows: TeraTerm (sets TERM=xterm). You need to set TERM=xterm-256color.

A couple of terminal emulator programs support even the entire RGB color space (16 million colors). To get this to work, at this date (2019), you need three things:

• The ncurses library version 6.1 or newer must be installed.
• You need a recent version of the respective terminal emulator program. See https://gist.github.com/XVilka/8346728 for the most recent developments in this area.
• You need to set the TERM environment variable to the corresponding value: TERM=xterm-direct instead of TERM=xterm or TERM=xterm-256color, TERM=konsole-direct in konsole, TERM=st-direct in st, TERM=mlterm-direct in mlterm, or TERM=iterm2-direct in iTerm2 on macOS.

2.1.2 Consoles

On OpenBSD 6 consoles, TERM=xterm produces better results than the default TERM=vt220.

On NetBSD 8 consoles, TERM=netbsd6 produces better results than the default TERM=vt100.

On Windows consoles, no TERM setting is needed.

2.2 The environment variable NO_COLOR

The environment variable NO_COLOR can be used to suppress styling in the textual output. When this environment variable is set (to any value), libtextstyle-enabled programs will not emit colors and other text styling.

This environment variable can be overridden by passing the command-line option ‘--color=always’ (see The --color option).

2.3 The environment variable NO_TERM_HYPERLINKS

The environment variable NO_TERM_HYPERLINKS can be used to suppress hyperlinks in the textual output. When this environment variable is set (to any value), libtextstyle-enabled programs will not emit hyperlinks. This may be useful for terminal emulators which produce garbage output when they receive the escape sequence for a hyperlink. Currently (as of 2019), this affects some versions of konsole, emacs, lxterminal, guake, yakuake, rxvt.

2.4 Emacs as a terminal emulator

Emacs has several terminal emulators: M-x shell and M-x term. M-x term has good support for styling, whereas in M-x shell most of the styling gets lost.

2.5 The --color option

The ‘--color=when’ option specifies under which conditions styled (colorized) output should be generated. The when part can be one of the following:

always

yes

The output will be colorized.

never

no

The output will not be colorized.

auto

tty

The output will be colorized if the output device is a tty, i.e. when the output goes directly to a text screen or terminal emulator window.

html

The output will be colorized and be in HTML format. This value is only supported by some programs.

test

This is a special value, understood only by some programs. It is explained in the section (The environment variable TERM) above.

‘--color’ is equivalent to ‘--color=yes’. The default is ‘--color=auto’.

Thus, a command that invokes a libtextstyle-enabled program will produce colorized output when called by itself in a command window. Whereas in a pipe, such as ‘program arguments | less -R’, it will not produce colorized output. To get colorized output in this situation nevertheless, use the command ‘program --color arguments | less -R’.

The ‘--color=html’ option will produce output that can be viewed in a browser. This can be useful, for example, for Indic languages, because the renderic of Indic scripts in browsers is usually better than in terminal emulators.

Note that the output produced with the --color option is not consumable by programs that expect the raw text. It contains additional terminal-specific escape sequences or HTML tags. For example, an XML parser will give a syntax error when confronted with a colored XML output. Except for the ‘--color=html’ case, you therefore normally don't need to save output produced with the --color option in a file.

2.6 The --style option

The ‘--style=style_file’ option specifies the style file to use when colorizing. It has an effect only when the --color option is effective.

If the --style option is not specified, the program may consider the value of an environment variable. It is meant to point to the user's preferred style for such output. The name of such an environment variable, if supported, is documented in the documentation of the libtextstyle-enabled program.

You can also design your own styles. This is described in the next section.

2.6.1 Creating your own style files

The same style file can be used for styling a certain type of output, for terminal output and for HTML output. It is written in CSS (Cascading Style Sheet) syntax. See https://www.w3.org/TR/css2/cover.html for a formal definition of CSS. Many HTML authoring tutorials also contain explanations of CSS.

In the case of HTML output, the style file is embedded in the HTML output. In the case of text output, the style file is interpreted by the libtextstyle-enabled program.

You should avoid @import statements, because

• - In the case of HTML output, the files referenced by the @import statements would not be embedded in the HTML output. In fact, relative file names would be interpreted relative to the resulting HTML file.
• - In the case of text output, @imports are not supported, due to a limitation in libcroco.

CSS rules are built up from selectors and declarations. The declarations specify graphical properties; the selectors specify when they apply.

GNU libtextstyle supports simple selectors based on "CSS classes", see the CSS2 spec, section 5.8.3. The set of CSS classes that are supported by a libtextstyle-enabled program are documented in the documentation of that program.

These selectors can be combined to hierarchical selectors. For example, assume a program supports the CSS classes string (that matches a string) and non-ascii (that matches a word with non-ASCII characters), you could write

.string .non-ascii { color: red; }

to highlight only the non-ASCII words inside strings.

In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements (CSS2 spec, section 5.12) are not supported.

The declarations in HTML mode are not limited; any graphical attribute supported by the browsers can be used.

The declarations in text mode are limited to the following properties. Other properties will be silently ignored.

color (CSS2 spec, section 14.1)

background-color (CSS2 spec, section 14.2.1)

These properties are supported. Colors will be adjusted to match the terminal's capabilities. Note that many terminals support only 8 colors.

font-weight (CSS2 spec, section 15.2.3)

This property is supported, but most terminals can only render two different weights: normal and bold. Values >= 600 are rendered as bold.

font-style (CSS2 spec, section 15.2.3)

This property is supported. The values italic and oblique are rendered the same way.

text-decoration (CSS2 spec, section 16.3.1)

This property is supported, limited to the values none and underline.

2.6.2 Debugging style files

If you want to understand why the style rules in a style file produce the output that you see, you can do so in three steps:

1. Run the program with the command-line option --color=html, redirecting the output to a file.
2. Open the resulting HTML file in a browser.
3. Use the browser's built-in CSS debugging tool.
   • In Firefox: From the pop-up menu, select "Inspect Element". Click somewhere in the DOM tree ("Inspector" tab) and look at the CSS declarations in the "Rules" tab.
   • In Chromium: From the pop-up menu, select "Inspect". Click somewhere in the DOM tree ("Elements" tab) and look at the CSS declarations in the "Styles" tab.

This technique allows you, in particular, to see which CSS declarations override which other CSS declarations from other CSS rules.

This document was generated by Bruno Haible on October, 9 2022 using texi2html 1.78a.