Apropos - apropos with a capital A

#!/bin/bash

## Apropos - with a capital A

# Search all man pages for a specific term and print an apropos (1)
# style output.

# ** default (non-capital) apropos command only searches
# man page names and short descriptions

man -KwI "$@" |\
  sed 's/.*\/\(.*\)\.[^.]*/\1/' |\
  sort -u |\

while read i ; do
  apropos -e -s ${i##*.} ${i%.*} |\
  grep "^${i%.*} "
done

# Commands explanation:

# man
#  -K searches all man pages.
#  -w shows the filepath to matching pages
#  -I forces case sensitivity
# $@ is script parameters

# sed
#  .*\/ is all characters up to the last slash in filepath
#  \(.*\) should match manpage-name.sectionnumber, e.g. xterm.1
#  \.[^.]* matches file extension on man page internal format.
#          i.e. a dot followed by non-dot characters
#          = usually .gz
#  \1 is the aforementioned match
# *** This regexp is not robust, but works.

# sort -u
#  = ditch duplicate results

# while read i
#  loop through all manpage-name.sectionnumber found
#  storing in variable $i

# apropos
#  -e goes for exact match of text string
#  -s chooses man page section number

# ${i##.} is all characters after the last dot in $i,
#  i.e. this should be the section number

# ${i%.*} is all characters up to the last dot in $i,
#  i.e. this should be the manpage-name

# grep
#  selects only lines beginning (^) with the right manpage-name
#  *** The apropos command will often return more than one result
#      due to the manpage-name being mentioned in the description
#      of another (likely related) manpage.

# FUTURE: Support regexps, which are blatantly ignored right now.