Man pages and ruby

05 Nov 2016

A man page is a form of software documentation usually found on a Unix or Unix-like operating system. Topics covered include computer programs, formal standards and conventions, and even abstract concepts. A user may invoke a man page by issuing the man command.

-- Wikipedia

I love man pages. I stopped counting how many times they helped me to figure out what I had to do. If I try out a new command line tool, I always do two things:

  • tool -h to check the brief explanation of the tool
  • man tool to skim through the documentation

This helps me a lot in understanding the tool. What does it offer? How do I have to use it and what can I expect from it?

Sadly right now it is really problematic to ship a man page with your ruby command line tool. Till last month you basically only had one option: gem-man, a gem developed by @defunkt more than 5 years ago. The way it worked was to add a new command to gem called gem man. And yes, you could alias it to man but it felt more like a hack than anything else. Calling a ruby programm just to open a regular non ruby man page sounded a bit absurd to me. Or the fact that you needed to remember if a tool is written in ruby to find it's man page. Imagine you would have to do that for every programming language.

But there is a better way. I wrote a gem plugin called manpages that scans for man pages during the gem installation phase and copies the files to a folder that the man command is able to find. No more aliasing or remembering if a tool is based on ruby. Install a gem and call man guard to see it's documentation.

How awesome is that?

Jump into the README.md and install it now. And more importantly: if you have developed a command line utility in ruby, please consider adding a man page for it.

comments powered by Disqus