How to slightly improve man pages

Here are a few tricks I’ve discovered that improved my man pages reading experience. The tricks are ordered by descending usefulness.

Lines are too long on a wide screen

I have a pretty wide monitor, and sometimes I end up opening a man page when the terminal window is the only window on screen. In this situation, the window is usually pretty wide and, as a consequence, man formats its lines to be pretty wide as well. There is no limit to how long the lines can get actually, and at a certain point it becomes extremely uncomfortable to read.

It’s fixable by closing man, making the terminal window smaller and running man again, but that is very annoying (especially if you are using a tiling window manager where all the windows try to take as much screen-space as possible). But there is a much better solution!

Man uses an environmental variable $MANWIDTH, to which we can write the desired width for our next man invocation. You can just set it to 72 or something, and the problem goes away! But I’ve gone an extra mile by writing a wrapper-function for man in my ~/.bashrc that tries to be a bit smarter when determining the width:

man() {
    local width="$MANWIDTH"
    if [[ -z $width ]]; then
        local cols
        let 'cols = COLUMNS + 1'
        local min_w=72
        local max_w=120
        width=$((cols > max_w ? max_w : (cols < min_w ? min_w : cols)))
    fi

    MANWIDTH="$width" MANPAGER='less -S' command man "$@"
}

In case you don’t know: functions defined in the ~/.bashrc become regular commands that you can run inside your shell. And such commands have precedence over regular programs. So, by defining the man function, typing man on the command line will invoke the man function instead of the man command. It allows us to do stuff we need to do before calling the actual man program with command man.

The function itself is pretty simple. We just take the amount of characters out terminal emulator can fit (via $COLUMNS environmental variable that bash exposes for us) and clamp it between 72 and 120 characters. If you don’t care about lines getting shorter than 72, you can just set it to 0.

Italics without breaking PDF output

Man pages are much more readable if italic text is actually rendered as italic, as opposed to underlined, which is the default. You probably know from some other source that we can just $MANROFFOPT environmental variable to -P-i, but it has one annoying problem: if you want to view a man page in a form of a PDF file with man -Tpdf, that no longer works; man will return this error:

Unknown option: i

I won’t delve into the explanation of why it happens, but, long story short, this option only works if man renders the page onto a terminal. We can fix it by writing a wrapper function for man again:

man() {
    local opt='-P-i'
    local arg
    local x
    for arg; do
        for x in '--troff' '--troff-device' '--html' '--gxditview' '--ditroff'; do
            [[ $arg = $x ]] && opt= && break
        done
        [[ $arg =~ ^-[[:alpha:]]*[tTHXZ][[:alpha:]]*$ ]] && opt= && break
    done

    MANROFFOPT="$MANROFFOPT $opt" command man "$@"
}

This one sets -P-i option only if we know it will play well with the rest of the options we specify.

Set terminal window title

A while ago I’ve written a patch for my dwl build that allows me to search for windows by title with dmenu because very often I have so many of them opened that I just cannot find the exact tag where a window resides in.

By default, man does not set the terminal window title to anything specific, and I’ve made another addition to my function wrapper that fixes that:

man() {
    local title="man $*"

    # Push current title and set a new one
    printf "\033[22;2t\033]2;%s\a" "$title" >> /dev/tty

    command man "$@"

    # Push previous title
    printf "\033[23;2t" >> /dev/tty
}

(You can change title to whatever you want, the current value just displays the command arguments.)

This is good, but I find it to be pretty useless now: most of the time if you lose the window with a specific man page opened, it’s much simpler to just rerun man again…

Fancy header

As you might have noticed, the previous tip wasn’t super useful but bear with me: this one is even worse.

Have you noticed that the first line of every man page has a header? It displays the man page title twice and the section where the man page belongs to. That is a very important piece of information!

Man pages are typically viewed using less pager and while reading its… man page I’ve encountered an interesting option:

--header=L,C,N
       Sets  the number of header lines and columns displayed on the screen.

This option allows us to define a header line that will follow us within the pager even if we scroll down. That way you can always know the man page you’re reading! Very handy! No

man() {
    MANPAGER='less --header=1,0,1 --no-search-headers' \
      command man "$@"
}

Full script

Here is a full wrapper function that makes use of almost all the tips I put down above. You can just copy it and put it into your ~/.bashrc if you got interested in the improvements it provides. (I do not care about the header line thing, so I commented it out.)

# Man wrapper
man() {
    local title="man $*"

    # Push current title and set a new one
    printf "\033[22;2t\033]2;%s\a" "$title" >> /dev/tty

    # Clamp width to (min, max)
    local width="$MANWIDTH"
    if [[ -z $width ]]; then
        local cols
        let 'cols = COLUMNS + 1'
        local min_w=72
        local max_w=120
        width=$((cols > max_w ? max_w : (cols < min_w ? min_w : cols)))
    fi

    # Set MANROFFOPT=-P-i only if we do not put any of the dangerous options
    # from below
    local opt='-P-i'
    local arg
    local x
    for arg; do
        for x in '--troff' '--troff-device' '--html' '--gxditview' '--ditroff'; do
            [[ $arg = $x ]] && opt= && break
        done
        [[ $arg =~ ^-[[:alpha:]]*[tTHXZ][[:alpha:]]*$ ]] && opt= && break
    done

    # Invoke man with our new settings
    MANWIDTH="$width" \
    MANROFFOPT="$MANROFFOPT $opt" \
    MANPAGER='less -S' \
        command man "$@"

    # Replace MANPAGER above with this if you care about the header line
    # MANPAGER='less -S --header=1,0,1 --no-search-headers' \

    # Pop previous title
    printf "\033[23;2t" >> /dev/tty
}