Spicy man pages

Preface

When using my computer I spend most of my time in the terminal, using my "${EDITOR}" of choice, compiling software, or reading the manual for software libraries. By default, the man pages are monochromatic with limited formatting to help the reader distinguish between things. I consider colour to be an accessibility feature for the reader who wishes to grok the page quickly when searching for a specific thing.

This post explores how I turned this:

into this:

There's also a call to action which I'd appreciate your help with.

The man command

Almost everyone who has used Linux distributions for more than a few weeks knows that there is a repository of useful knowledge on their computer. They are of course, man pages. One accesses the man pages via the man command, e.g.:

man openssl

It derives its behaviour from a number of environment variables, directly and indirectly. The environment variables of interest to us are (initially) PAGER and MANPAGER. A pager, if you're unfamiliar with the term, is a program which consumes and displays text. Common pager programs include more, less and most.

PAGER is used by a variety of programs which output text, to determine which pager to use. man will use that, but in the presence of MANPAGER it will prefer the latter.

Adding colour

Preparation

Gnome Terminal and Konsole seem to require the environment variable GROFF_NO_SGR=1 to be set for the following features to work.

export GROFF_NO_SGR=1

The first thing we'll do is ensure less is used as the pager for man:

MANPAGER="less"

Then, we'll add some line numbers:

 --LINE-NUMBERS

Next, we'll inform less to enable its colour features:

 --use-color

Things we can intercept

less can intercept a variety of inputs:

We'll use the d, u and N codes.

4-bit colours

less can use 4-bit colour codes:

Configuring the Colours

At this point, we can instruct less to use a 4-bit colour letter to add red to line numbers:

 --color=N+R

see the man page for less for the details in the OPTIONS section.

Any bold text it encounters can be coloured yellow using another 4-bit colour letter:

 --color=d+y

Finally, we can use an 8-bit colour code to add an orange colour to underlined text:

 --color=u+208

Putting it all together:

export GROFF_NO_SGR=1

export MANPAGER="less --LINE-NUMBERS --use-color --color=N+R --color=d+y --color=u+208"

Invoking man openssl should now yield a colourized man page! I find this far more appealing and easier to scan quickly. You may disagree with my colour choices. If you do please free to improve upon them and report back.

COLUMNS

The line numbers take up some of the width of the screen, causing the text to wrap around. We have three options:

• Disable line numbers (remove --LINE-NUMBERS from our command)
• Manually account for the line numbers
• Disable line wrapping by specifying the --chop-long-lines option

I tend to disable line wrapping.

Raw control characters

It's often useful to specify that raw control chars be displayed. If you've ever seen something like \x1b[31mSome text\x1b[0m then you've encountered control characters. They tell software and the terminal itself to do certain things.

To enable this, add to less: --RAW-CONTROL-CHARS.

Contamination from LESS

less derives some of its configuration from the LESS environment variable. It may be necessary to prevent this from contaminating less inside our MANPAGER.

LESS='' MANPAGER='...'

No init

It may be beneficial to ignore TERMCAP init/de-init when using less:

 --no-init

What should we do with this knowledge?

I think the default user experience of reading man pages could and should be improved by enabling colour to the pages as shown. There are two main methods to do so:

Export MANPAGER from ~/.bashrc

I the export could be included in user's .bashrc where appropriate, both on the desktop and server.

export GROFF_NO_SGR=1

export MANPAGER="less --no-init --RAW-CONTROL-CHARS --LINE-NUMBERS --use-color --color=N+R --color=d+y --color=u+208"

Though, this may seem a bit intrusive to some people.

Add a BASH alias

We could instead add an alias:

# File: ~/.bash_aliases

alias manual='MANPAGER="less --no-init --RAW-CONTROL-CHARS --LINE-NUMBERS --use-color --color=N+R --color=d+y --color=u+208" man'

and use it:

manual openssl

Round-up

We've shown that man pages can be displayed in a more colourful fashion. I would like to hear your thoughts on the matter. Please join the discussion to improve on the presented idea, and show your support for implementing it as a default in Linux distributions.

Resources

Here are a few resources to help you on your way:

• man man
• man less

What!?!? Man pages as resources!?

Yes! I didn't go to all this effort just to recommend web pages!