Adding color to man pages

How to colorize man pages in your terminal

Adding color highlighting to the man pages is similar to code syntax highlighting. I find adding color to the pages helps differentiate variables, strings, and reserved words and makes it easier to visually parse the information presented. I accomplish this by passing ANSI color code parameters to the less pager used in display the man pages.

• Configuration Steps
• Notes on groff rendering
• Alternate Color Theme
• How it all works
• ANSI Color Codes
• References

Configuration Steps

1. Open your .bashrc file in an editor and add the following lines: 

 
LESS_TERMCAP_mb=$(printf "\e[01;31m") # enter blinking mode(bold red)  
export LESS_TERMCAP_mb  
LESS_TERMCAP_md=$(printf '\e[01;38;5;75m') # enter double-bright mode  
export LESS_TERMCAP_md  
LESS_TERMCAP_me=$(printf "\e[0m") # turn off all appearance modes  
export LESS_TERMCAP_me  
LESS_TERMCAP_se=$(printf "\e[0m") # leave standout mode  
export LESS_TERMCAP_se  
LESS_TERMCAP_so=$(printf "\e[01;33m") # enter standout mode(bold yellow)  
export LESS_TERMCAP_so  
LESS_TERMCAP_ue=$(printf "\e[0m") # leave underline mode  
export LESS_TERMCAP_ue  
LESS_TERMCAP_us=$(printf '\e[04;38;5;200m') # enter underline mode (magenta)  
export LESS_TERMCAP_us  
  
# Turn off Select Graphic Rendition(SGR)  
# export GROFF_NO_SGR=1  
# Start with color output disabled (avoid unexpected color code output)  
export MANROFFOPT="-c"  
  
# Set options for how less will be used as a pager. 
# The MANPAGER environment variable will override 
# settings used by the more general PAGER settings.  
# In this case, I want to show percentage of page 
# completion for man pages  
export MANPAGER='/usr/bin/less -s -M +Gg'  
export PAGER='/usr/bin/less -s -M'

  

2. Source the .bashrc file (source .bashrc) to read and execute the newly added commands into the current shell.

Notes on groff rendering

Two lines of note in the above configuration: export GROFF_NO_SGR=1 and export MANROFFOPT="-c". One of these is needed in the configuration in order for the man page colorization to work. As I learned this week, there is an issue with newer versions of groff(i.e. newer than 2023)

See the following for details:
Groff + most change in behaviour
Displaying a man page on a terminal with/without my favorite pager shows garbage

Alternate Color Theme

Here is a slightly different color theme:

 
export LESS_TERMCAP_mb=$(printf '\e[01;31m') # (red)
export LESS_TERMCAP_md=$(printf '\e[01;35m') # (bold, magenta)  
export LESS_TERMCAP_me=$(printf '\e[0m')  
export LESS_TERMCAP_se=$(printf '\e[0m') 
export LESS_TERMCAP_so=$(printf '\e[01;33m') # (yellow)  
export LESS_TERMCAP_ue=$(printf '\e[0m') # 
export LESS_TERMCAP_us=$(printf '\e[04;36m') # (cyan)  

Generally, I have come to prefer separating out the color variable definitions from the statements exporting the variable as shown in the first configuration example. This alternate theme example will also work; but, shellcheck gives me an error: SC2155: Declare and assign separately to avoid masking return values. I try to pay attention to tools that I use when they make recommendations that could improve my code and configurations.

See Shellcheck error SC2155 for additional details.

How it all works

To quote liberally from Russell Parker’s post Adding Colors to man

To understand how the above environment variables work it helps to review what steps normally happen when viewing a manpage:

1. man renders a page from a (likely compressed) nroff or troff/groff document and pipes the result it into the pager program, usually less
2. If the piped text indicates formatting that needs to be performed then less has to figure out how to accomplish this for terminal output
3. less uses the (deprecated) termcap database to look up how to achieve effects like underline and bold. In reality it ends up using termcap’s successor, the terminfo database, which maintains support for the termcap interface. This gives back an escape string which corresponds to the specified effect for your particular terminal
4. Using these nifty escape strings, less finally displays the manpage to the user

Manpages use formatting like bold (for sections) and underlines (for things like file names and arguments). These should already work out of the box when using the man command but will not change the text color.

ANSI Color Codes

To see the ANSI color codes and how they would look on your specific terminal, here is a bash script to print them out.

 
#!/bin/bash  
# name: ansi_codes.sh (see References for link to source)  
for x in {0..5};  
  do echo === && for z in 0 10 60 70;  
  do for y in {30..37};  
  do y=$((y + z)) && printf '\e[%d;%dm%-12s\e[0m' "$x" \
  "$y" "$(printf ' \\e[%d;%dm] ' "$x" "$y")" && printf ' '; 
  done && printf '\n';  
done;  
done

The References section below contains links to several color charts.

References

• 5 cool terminal pagers in Fedora
• Tutorial: How to Color Man Pages & How It Works
• How to Display man Pages in Color on Linux
• Color man pages in Linux
• Bash Colors
• ANSI Escape Codes
• entire table of ANSI color codes
• List of ANSI color escape sequences
• Adding Colors to man
• Groff + most change in behaviour
• grotty - groff driver for typewriter-like devices
• Displaying a man page on a terminal with/without my favorite pager shows garbage
• Script for print ANSI color codes