After I got my copy of the ruby book and went thru the rubygems packaging, I
tried repackaging my getopt-declare library as a gem.
It worked fine, but I did run into a stumbling block, when it came to the ri
documentation.  Currently, due to its length, I keep the rdoc documentation in
a separate file.

My gemspec looks like:

require 'rubygems'

spec = Gem::Specification.new do |s|
  s.name = 'getopt-declare'
  s.version = "1.09.7"
  s.author = "Gonzalo Garramuno"
  s.email = "GGarramuno / aol.com"
  s.homepage = "http://getoptdeclare.rubyforge.org/"
  s.platform = Gem::Platform::RUBY
  s.summary = "Comprehensive and easy to use command-line parser library using
regular expressions (port of Perl's module)."
  s.files = Dir.glob("{samples,tests,lib,docs}/**/*").delete_if {|item|
item.include?("CVS") || item.include?("rdoc")}
  s.require_path = 'lib'
end

if $0==__FILE__
  Gem::manage_gems
  Gem::Builder.new(spec).build
end

and the documentation is in a file inside the docs directory as
docs/Declare.rdoc.
I've tried also adding the s.extra_rdocs_files and listing in there without
success.

Whenever I install, I get:
WARNING: Generating RDoc on .gem that may not have RDoc.

and obviously 'ri' remains unaware of the new module(s).