Generic skeleton template for a command line utility written in Ruby

gistfile1.rb

#!/usr/bin/env ruby
# encoding: UTF-8
'di '
'ig00 '
# This is both a Ruby script and a man page; you can symlink it into your
# man directory as commandname.1 or run man -l on this file.

# This is a generic skeleton for a Ruby command-line utility, showing how to
# make the same file work as both a Ruby script and a man page, for ease of
# distribution. This cool hack brought to you by mathew <meta@pobox.com>.

if ARGV[0] == '--help'
  system("man #{$0}")
  exit 0
end

# Your code goes here

exit 0
__END__

.00
'di
.TH commandname 8 "20 Jun 2011"
.SH NAME
commandname \- do something smart
.SH SYNOPSIS
.B commandname \fI--option\fR
.SH DESCRIPTION
.PP
This is a thing that does some stuff.
.PP
Oh look, here's another paragraph.
.PP
.SH BUGS
You may get scary looking warnings that say "Status: Before uninstall, this
module version was ACTIVE on this kernel." The kernel the error message refers
to the one it is uninstalling, not the one you are running, so don't worry.
.SH AUTHOR
Herp Derpington <herpderp@example.com>
.SH COPYRIGHT
Copyright message would go here. This file is not copyrighted, so that you can
use it as you see fit in any project you like.

You should check out gem-man, ronn, and OptionParser. ronn lets you write a man page in markdown and gem-man lets you read it via gem man your_app

OptionParser is certainly a good option (ha!), though it's significant work to provide help for all the options there as well as writing the man page, and I'm not convinced that mingling code and error messages that way is a good idea. Then again, that could just be the OS X and Java influence telling me it's bad because of i18n.

I came up with this hack because I was looking for something to replace RDoc::Usage, which Eric Hodel removed without notice in Ruby 1.9. http://redmine.ruby-lang.org/issues/show/2713
Given the choice, I can live without OptionParser-style help, whereas utilities lacking a man page makes me rage.

Ronn looks like a good way to write the man page, I'll probably use that next time rather than writing nroff directly.