mjhjmtu

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.

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

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

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 () \[

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.

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" 

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.

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

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.

Hope this help.

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"