Search all the man-pages in one command.

README.md

whichMan, a CLI tool that lets you find the right manpage

Usage

whichMan.sh "some string that may appear in some package's manpage"

Why ?

Because sometimes I don't know which manpage to consult to get info about something.

This tools greps all the manpages for that something, then shows you excerpts of what it found and that helps you find or decide which manpage to consult to get in depth info about the subject you're researching.

Here's a good example:

man -aK does this too, more or less, but it makes you cycle manually through each manpage it finds and doesn't provide you with a good overview of the matches.

It is barely usable.

In the above case man -aK localoptions would have sufficed since only one manpage matches.

But in the case below, man -aK 'brace expansion' shows its limits. You have to cycle through all the packages.

Whereas my script returns:

So with whichMan 'brace expansion', in a single glance, you understand that to go more in-depth you need to run:

man zshexpn

This script aims to correct the poor behavior of man -K

It doesn't seem to work with bash, for some reason I haven't yet investigated, so currently the script is zsh-only.

zsh is the best shell anyway, so give it a go, but always customize it with ohmyzsh, because the defaults suck and zsh will actually seem worse than bash until you've configured it properly.

Why the unreadable one-liner ?

For the fun of it, and to level-up in shell scripting.

I know this tool could have been written in a way more readable way, and I will do it too, eventually.

whichMan

#!/usr/bin/env zsh

# Usage: whichMan.sh 'some string that may be in some package's manpage'

# Why ?
#
# Because sometimes you don't know which manpage to consult
# to get info about something.
#
# This tools greps all the man-pages for that something,
# then show you excerpts of what it found and helps you
# decide which man-page to consult to get info about
# that particular subject.
#
# man -K does this, more or less, but makes you cycle through each
# man-page manually and doesn't provide you with a good overview.
# This script aims to correct that.
#
# Doesn't seem to work with bash, for some reason I have not yet investigated,
# so currently it is zsh-only - the best shell anyway.
#
# Why the unreadable one-liner ?
# For the fun of it, to level-up in shell scripting.
# I know this tool could have been written in a way more
# readable way, and I will do it too, eventually.

(export QUERY=$1; \
man -waK $QUERY | grep '.gz' | sed -r 's/^([^.]+)\..*$/\1/' | \
xargs -n1 basename | xargs -n1 -I% sh -c \
'{ echo "\n[####] \033[0;32mFound match in the man page of < % >:\033[0m\n"; \
man % | grep "$QUERY" -i -A2 -B2 --color=always; echo "\n"; }')