Russell Parker

In a previous post I explored using colors with man. Here are a few more adjustments to make browsing manpages nicer.

Section Navigation

We can make navigating the sections of a particular page a little bit easier. By default, there is no simple way to do this. Going off of this forum, we can add some searchable text to denote a section heading:

.\" man.local
.\" Add a searchable string before each section header
.rn SH SH-orig
.de SH
.SH-orig \(sc \\$*
..

This file, man.local, defines a groff macro that uses the escape code \(sc to prepend the glyph § to section headings. The result looks like this:

§ NAME
       man - an interface to the on-line reference manuals

This makes it simpler to navigate a man page because we can search for the glyph and go to the next and previous section with n and N, respectively. less keeps a history so repeating a previous search is easy, but we can also create a key-binding that automates this.

# ~/.lesskey
#command
    # remap tab to search for section
    \t forw-search §\r

Note: #command is not a comment but a required directive.

This can be compiled for less with the lesskey command which will bind Tab to searching for the above glyph.

Prompt

The prompt is a ribbon of text displayed at the bottom of a less screen. man has a default prompt which attempts to show the total number of lines and the current position as a percent. Since the formatted manpage is piped into less though the program does not know about the total length. If you reach the bottom of a file though (try the G command), this additional information will be displayed. A hack to jump to the end of a file and back again is:

# ~/.bashrc
export MANPAGER='less +Gg'

This tells less to run the commands G and g when opening a file which scans to the end of the input and then back to the beginning. By doing this, less figures out the total length of the file and can print the total line numbers and current percent in the ribbon. The tradeoff is that this can cause a noticeable performance hit when opening large man pages like bash. This can also be accomplished by setting the LESS environment variable but doing so can interfere with other programs that use less.

The prompt itself can be simplified somewhat as well to get rid of the overbearing “(press h for help or q to quit)” message.

# ~/.bashrc
export MANLESS='\ Manual\ page\ \$MAN_PN\ %lt/%L %pB\%'

Line Length

I find reading manpages in wide terminals more difficult (although it may make skimming easier). Setting a maximum line width for man. MANWIDTH does exactly this but will hard-code the value instead of acting as a maximum. A solution is to put some logic in a BASH_PROMPT function.

# ~/.bashrc
export PROMPT_COMMAND=prompt
prompt() {
    # set line width for man pages with maximum of 80
    if [ $COLUMNS -lt 80 ]; then
        export MANWIDTH=$COLUMNS
    else
        export MANWIDTH=80
    fi
}