How to jump to a specific heading in a man page?

Solution 1:

From the command line for GNU man:

man --pager='less -p ^ENVIRONMENT' man

or for BSD man:

man -P 'less -p ^ENVIRONMENT' man

will jump to the "ENVIRONMENT" heading of the man page for man.

Here is a handy function:

mans () {    # Bash
    local pages string
    if [[ -n $2 ]]
    then
        pages=(${@:2})
        string="$1"
    else
        pages=$1
    fi
    # GNU man
    man ${2:+--pager="less -p \"$string\" -G"} ${pages[@]}
    # BSD man
    # man ${2:+-P "less -p \"$string\" -G"} ${pages[@]}
}

Examples:

Use normally:

mans bash

Go to the "DESCRIPTION" heading:

mans ^DESCRIPTION bash

Go to the "DESCRIPTION" heading of each man page in succession (press q and Enter to go to the next one):

mans ^DESCRIPTION bash ksh zsh

Go to the "Parameter Expansion" sub-heading (you can search for any string using regular expressions):

mans '^ *Parameter Expansion' bash

Search for the most recent regex you've used in Less:

mans '' bash

The match that you searched for won't be highlighted. If you'd prefer it to be, just remove the -G from the options to less.

This function makes no attempt to handle the other arguments and options that man supports.

Solution 2:

You can use PAGER variable for this run to avoid BSD/GNU compatibility problem.

Use " quotes if the section title contains spaces:

PAGER='less -p ^"ENVIRONMENT"' man man

---

Solution 3:

I don't like the --pager/-P solution, because man might be used but not be called directly (e.g. when you use git help ...). So using an envvar is more flexible. But I find using PAGER='less ... kind of redundant, because less is usually the default pager anyway. You can use the LESS envvar to pass on parameters directly to less. This also has less quoting issues. E.g. this will correctly jump to the right section, even though it has a space in it:

LESS="-p file system" git help glossary