Man pages and ruby
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.
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 -hto check the brief explanation of the tool
man toolto 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 man. And yes, you could alias it
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.