Man and Ruby

If you've found this blog it's likely that you are at least somewhat familiar with Unix and Unix-like operating systems. If so you undoubtedly know about Man pages. For those of you who don't; the man page is the unix system for documenting command-line applications. They are succinct and clear guides to how you can interact with an application. If you are on a *nix system you can pop open your terminal right now and type man man and see what I'm talking about. As developers, we often baulk at documenting our code. We enjoy creating new things, not tediously writing about our last project. Here I'll give a brief overview of how you can incorporate man pages into your workflow, then show you how easy it can be to create this basic documentation. Trust me, you'll make a lot of friends if you do it, and probably find that its not as tedious as you think.


Using man is easy as typing 'man < command_name >'. If you want to view a specific secition of a man page you can type 'man < section_number > < command_name >'. The beauty of man pages and Unix is that it really is that simple.

Michael Edgar submitted a patch [1] to rubygems to allow for explicit inclusion of man pages in the gemspec or implicit inclusion in the /man directory. Unfortunately this patch has not been included despite being projected for inclusion in 1.4. All is not lost, @defunkt, of GitHub fame and huge proponent of man page usage, wrote a nice little plugin called gem-man [2].

Gem-man checks to see if any man pages exist and displays it accordingly. If multiple man sections are found it will provide you with an option to select one. It can be installed like so.

gem install gem-man
gem man gem-man

If you pass gem-man the -s argument it will fall back to searching system files for your man page. With that in mind you can create an easy alias which will let you use man to search both your systems man pages and any man pages found in your gems: