Documentation on LESS_TERMCAP_* variables?

Termcap is a library that Less uses to access the terminal. Termcap is largely obsolete, having been replaced by Terminfo, but Terminfo offers a Termcap compatibility interface to applications. Less is content with the Termcap interface and uses that.

The Termcap library is a description of the terminal's facilities. Each facility is identified by a two-letter (or more generally two-character) code. For example, hc identifies hardcopy terminals (i.e. printers, not screens); co is the number of columns; md starts displaying bold text. Each capability has a value, which can be a boolean (as with hc), an integer (as with co) or a string (as with md). Many of the strings are escape sequences that applications can send to the terminal to achieve a certain effect.

Why escape sequences? Because the interface between the terminal and the application is a character stream (more precisely, one character stream in each direction: one for user input, one for output to display). When an application writes a character to the terminal, it is usually displayed. A few characters have a different behavior: they are control characters, which do things like moving the cursor around, switching display attributes, etc. There are a lot more commands than control characters, so most commands are accessed by escape sequences, which begin with a special character (often the escape character, hence the name).

For example, when Less wants to display some bold text, it looks up the value of the md capability. This is a string, which Less writes to the terminal. The terminal recognizes this string as an escape sequence, and adjusts its internal state so that subsequent characters will be displayed in bold.

In the early days of hardware terminals, different brands had different escape sequences and capabilities; the Termcap database and interface was invented so that applications wouldn't have to know about every terminal model. Nowadays most terminal emulators have very similar capabilities, but the Termcap or Terminfo database is still useful to cope with minor differences.

The LESS_TERMCAP_* variables can be set in the environment or in the .lesskey file. It provides Less with alternative values for Terminal capabilities. When Less wants to use a terminal capability, say switch to bold, it first checks if there is a LESS_TERMCAP_md variable. If this variable exists, Less uses its value as the escape sequence to switch to bold. If not, it uses the value from the Termcap database. This mechanism allows the user to override Termcap database settings for Less.

The most useful LESS_TERMCAP_* settings are escape sequences. You can map attributes to different attributes. You can use the tput command to look up the value of a capability for the current terminal in the system's Termcap or Terminfo database. You can use escape sequences directly if you don't mind being terminal-dependent. For example, this setting tells Less to display in bold red when instructed to display in bold:

LESS_TERMCAP_md=$(tput md; tput AF 1)

or if your tput command doesn't support Termcap names:

LESS_TERMCAP_md=$(tput bold; tput setaf 1)

Man sends Less text with some very simple formatting that can only express bold and italics. In addition, Less uses various formatting capabilities for its internal use, such as to highlight search results and to display the mode line at the bottom. Here are some of the escape sequences that Less uses (I only list capabilities that it is reasonably useful to remap):

termcap terminfo  
ks      smkx      make the keypad send commands
ke      rmkx      make the keypad send digits
vb      flash     emit visual bell
mb      blink     start blink
md      bold      start bold
me      sgr0      turn off bold, blink and underline
so      smso      start standout (reverse video)
se      rmso      stop standout
us      smul      start underline
ue      rmul      stop underline

To show output in color, use the setaf capability (or AF with Termcap).

The LESS_TERMCAP_* settings are not mentioned in the LESS documentation. The best reference I can offer is my answer here.

Gilles answer is excellent, but this made me curious:

Termcap is largely obsolete, having been replaced by Terminfo

1. If Termcap is obsolete, I want to switch to Terminfo

2. I also want to switch away from Termcap because I found a bug. Say you put a termcap variable in your ~/.profile or similar:

   export LESS_TERMCAP_so=$(printf '\33[5;30;43m')
   export LESS_TERMCAP_se=$(printf '\33[m')
   

   After that if you enter set, the Termcap variables mess up your color output.

To switch to Terminfo, you can make a file xterm-pretty.ti:

xterm-pretty|xterm with pretty colors,
# exit standout mode
  rmso=\e[m,
# begin standout mode
  smso=\e[5;30;43m,
# similar terminal
  use=xterm,

Compile and install the file:

tic xterm-pretty.ti

Add line to ~/.profile or similar:

TERM=xterm-pretty