------------------------------------------------------------
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
