Reading and searching long man pages

Question

I finally got fed up when wanting to read about bash's read and it's -s option with man bash. I found the right spot eventually (around line 4500), but it was a frustrating as usual, since both /read and even /\s-s\s searches have way too many matches.

So, the question is: How can I read long man pages efficiently, or get same information in other ways, locally? As a specific example, how to reach the relevant documentation after seeing read -s pwd in a shell script? A good answer could be a shell script snippet, or hint about some tool and how it is used, or something else entirely, as long as it helps in finding the right spot to read.

Note: I'm not tagging with bash because I want the question to be about man page reading in general, even though that quite possibly is the most commonly encountered humongous man page.

Answer 1

For quickly getting help on a Bash builtin, use help:

help read

is what you want.

For man-page-like formatting, use

help -m read

or, even better,

help -m read | less

If you still insist on looking for it in the man page, I find what quickly gets me to a command's explanation is

/^\s*read [[]

This works because when a command is first explained, its name is indented slightly from the start of the line. In the particular case of read, this takes a little browsing before you get to the actual read documentation because (for obvious reasons) the word "read" is repeated a lot throughout the man page. The [[] means to match a [ which usually precedes optional parameters. (I usually leave out /^\s* and simply do /<built-in command> [[])

Another alternative

If you don't mind the format change, you can convert your man page to a DVI or PDF file:

man -T dvi bash >bash.dvi

or

man -T ps bash | ps2pdf - bash.pdf # Requires the Ghostscript suite for ps2pdf

Of course, given a DVI or PDF document, you can then do a text search easily.

Answer 2

Approach 1

man bash then /read \[ then /-s

Approach 2

You may try an open source tool for explaining command-line arguments called explainshell.

It can be used locally. Read documentation on https://github.com/idank/explainshell

Caveats: Usually works, but only with commands found in Ubuntu's manpage repository

In your case, it cannot recognize -s switch in read -s pwd.

Approach 3

I have found another tool that seems promising but it does not work on my system.

explain: Short Documentation for Unix Commands

Answer 3

What I usually do in this case is just run man, search for the SHELL BUILTIN COMMANDS heading, then search for the builtin, i.e.

man bash
/^SHELL BUILTIN
/  read 

however, in bash you can do

help read

or, depending on the system, either of

man 1 read
man bash-builtins

In general, I have a script called he ("short help") to do this. You would run it like this:

he bash read

Answer 4

There is no generic way to finding information in a man page, any more than there is a generic way of finding information in a book. It depends on what you're looking for.

When you're looking for information about a shell builtin, you can search for the builtin at the beginning of a line save for indentation, and followed by a space: search for ^ *read␣ (e.g. type /^ *read␣ Enter) (␣ is a space). This works with dash, pdksh, mksh and bash. Zsh's man page is split so you need to read the zshbuiltins man page. Ksh93 has special symbols before the names of some builtins, you need to search for ^ *†*␣ in UTF-8 or ^ *-*␣ in ASCII. There are a couple of false positives but this will get you quickly to the right line. Searching for ^ *read($| [-[]) reduces the amount of false positives.

You can speed up the search by telling your pager where you want to go. For example PAGER='less "+/^ *read \["' man bash opens the bash man page on the description of the read builtin. You can make this a function:

man-builtin () {
  PAGER="less '+/^ *$1(\$|\\[|-)'" man ${SHELL##*/}
}

Answer 5

To jump directly to the SHELL BUILTINS COMMANDS section of the bash man page, I define the following alias in my $HOME/.bash_aliases file.

alias man-builtin="man -P 'less -p ^SHELL\ BUILTIN\ COMMANDS' bash"

Answer 6

Putting together the pieces from the other discussion here here's a quick function you can leave in your .bashrc that will get you directly to the built-in (if it exists). Otherwise it opens man as normal:

man() {
    case "$(/bin/bash -c 'type -t '"$1")" in 
        builtin)
            LESS=+?"^       $1 " command -p man bash
            ;;
        *)
            command -p man $@
            ;;
    esac
}

Answer 7

From any Linux distro you should be able to use info bash if you want to have separate paragraphs by type of action where the information are identical to man pages.

Answer 8

I got around to creating a bash function for the purpose. This snippet can be for example pasted at the end of ~/.bashrc:

manfind() {
  # required args
  test "$1" -a "$2" || return 1                  

  # create temp file and get its name
  local tmp=$(mktemp /tmp/manfindXXXXXX) || return 1
  ( # subshell for trap
    trap "rm $tmp" EXIT

    # grep all matching lines with line numbers and pipe them to dialog
    if man "$1" |                   # get the whole man page
      grep -n "^\s*$2" |            # grep for the search string, with line nums
      sed 's/:/\n/' |               # replace line num separator with newline for dialog
      cut -c-70  |                  # cut long lines to nice length
      xargs -d'\n' -n 999999 \
        dialog --output-fd 3 --menu "Select line to go to" 0 0 0 3>$tmp -- 1 '(start of man page)'
    then
      # selected line number is now in $tmp, get man page and
      # use vim in read only mode to view it at right line
      man "$1" | vim -R +"$(< $tmp)" -
    else
      # cancel selected from dialog
      exit 1
    fi
  )
}

Comments explain a bit about what it does. The default search string in particular searches given word from the beginning of lines, skipping initial space. Examples:

# find every line which starts with 'read' followed by space
manfind bash 'read '
# research bash subshells
manfind bash '.*subshell'

Note: This script has no concept of man page sections... I'll see if I tweak that later, but setting MANSECT environment variable of man helps.

Answer 9

Just to offer another alternative, if you prefer using a web browser which allows you to easily search through the current page, you can use something like man.cgi used at freeBSD.org which also lets you view man pages from different systems to see how they differ. I have seen similar on other sites so expect there are other variations around.

The help link under apropos offers some info to get a copy of the script to put on your own server with links to download the man page collections.