------------------------------------------------------------
       Technology/manpages, (sdf.org), 11/08/2018
------------------------------------------------------------
Who doesn't like their manual pager[1]? I use the 'man' 
command all the time, mostly because I can't possibly be 
imposed upon to remember the many varied options for every 
command on my system. Life would be a lot harder if the 
manual pages weren't around.

Apart from raw utility, manual pages can actually be quite 
beautiful in terms of formatting. A really well-put-together 
manual page leaves the reader satisfied, and leads to 
quicker answers and higher productivity. Praises be to the 
troff wizards for all that they have given us through the 
years.

Of course, the real beauty of a *nix system is what each
particular user does with it... so, let me write a little 
bit about what I do to augment my man usage. Though I love 
'man' dearly, I find that it is sometimes far too extensive 
in scope. For commands that I'm just learning, it's awesome. 
For old commands that I don't use all that often, but that I 
have a basic understanding of, it's usually a matter of 
wading through an excess of info to find the little thing(s) 
that I have forgotten.

Enter the 'mman' command. mman is a tiny script that lives 
in my ~/bin folder. It is nothing more than a glorified way 
to run 'cat' on a text file in a particular folder. 
Specifically, it does this:

```
#!/bin/sh
# mman displays text files with custom user help


if [ "$#" -lt "1" ]; then
        echo "Usage: mman <command>"
        exit 1
fi

MMANFILE="/home/*scrubbed*/share/mman/$1"

if [ ! -f "$MMANFILE" ]; then
        echo "You haven't written a mman page for \"$1\", go 
do it now."
        exit 1
fi

/bin/cat $MMANFILE
```

Nothing special, at all. In fact, it looks rather useless. 
If someone had shown me the above shell script, I would have 
said to myself "um, that's stupid. Why not just type 'cat 
/path/to/file.txt'?"

Why not indeed. The answer is: laziness and muscle memory. 
I'm already used to hammering out 'man <command>' when I 
need help; typing 'mman <command>' feels quite natural as an 
extension to that.

The magic sauce of the silly mman script is in the content 
of the text files. In my /home/.../share/mman/ folder I have 
text files named after a few commands that I use just 
infrequently enough to be annoying. In those text files I 
have written down just the bits that always seem to elude my 
memory, or that get jumbled in my memory, and that I would 
normally have to wade through the man page to find. It's a 
custom help file for me, to make my life easier.

Here's one example: I like to listen to music using cmus. 
But, I can only focus on my work some of the time while 
listening to music, so my listening is not a daily activity 
(it's maybe weekly or less, depending.) I've been too lazy 
to memorize the basic controls in cmus- I always mix up the 
media controls at the 'zxcvb' keys. My 'mman cmus' text file 
shows me this:

+-------------------------------+
|      CMUS Media Controls      |
|-------------------------------|
| h   z   x    c    v    b   l  |
|-------------------------------|
| <<  <   [>   ||   []   >   >> |
|-------------------------------|
| s   p   p    p    s    n   s  |
| e   r   l    a    t    e   e  |
| e   e   a    u    o    x   e  |
| k   v   y    s    p    t   k  |
| -            e             +  |
+-------------------------------+

   m  - toggle artist/album/all
   s  - toggle shuffle
   r  - toggle repeat
  ^r  - toggle repeat current
   i  - jump to current
  +/= - volume control
 
Nothing fancy, just a quick and easy-to-read layout of the 
cmus media keys. I type 'mman cmus' and get a quick review, 
then I'm ready to use cmus for that day.

Perhaps I'll eventually memorize the cmus keys and my music 
listening will become frequent enough that I won't forget 
them. Fine, I'll just ignore or delete the mman text file.

When I find a command that I frequently access the man page 
for, I attempt to write a quick mman page for the bits that 
I am repetitively looking for. That way, I can get the help 
I need even quicker and easier than I can from 'man.'

[1] gopher://gopherpedia.com:70/0/Man page