From: Johan Nilsson <johan.nilsson@...>
Date: 2005-02-11T21:50:02+09:00
Subject: RDoc::usage and RubyGems application

Hi,

I noticed a problem when using RDoc comments to display program usage (as
described in PickAxe II) - when the application is distributed as a
RubyGem.

As the script defined in Gem::Specification::executables is wrapped and
loaded by a higher-level ruby script under <ruby-root>\bin, calling
RDoc::usage results in the text from the higher-level script being
displayed, e.g.:

#
# This file was generated by RubyGems.
#
# The application 'yourapp' is installed as part of a gem, and
# this file is here to facilitate running it.
#

... which is not very enlightening ...

It sure would be nice to have the ability to specify the file from which
RDoc::usage[_no_exit] should extract the documentation.

To make my own application work, I made a hack and replaced
RDoc::usage_no_exit with code that checked:

1. Checked if there were any arguments passed
2. If so, checked if the first argument was an existing file (e.g.
File.exists?)
3. If so, used that file instead of the top-level ruby script and removed
the filename from the args before passing the remaining arguments on
further.

This at least allowed me to use e.g. RDoc.usage(__FILE__) where I needed to.
I realize that this won't help the people that rely on being able to call
RDoc.usage from everywhere in the program and still display information from
the main ruby script - but it might at least give some insight to my
problem.

Where should I report a feature request for RDoc?

// Johan