[Rubygems-developers] "readme" specification and repository support

[Gavin Sinclair]

Folks,

Something I've been thinking about for a while is a gemspec having a
"readme" specification, which names the file that fulfills what we
might call the "README" role: i.e. gives a user an overview of the
package.  Shall we agree that most projects have such a file, and that
most users want to see it?

Typical "README" files in an English-language Ruby project are README,
README.txt, README.en, README.en.txt, etc.  It would be possible, but
perhaps not practical, for RubyGems to 'find' a README-like file
amongst the list of files in the event that none was specified.

Anyway, it would basically look like

  spec = Gem::Specification.new do |s|
    ...
    s.readme = "README.txt"
    ...
  end

The purpose of this specification is to enable RubyGems frontends to
present the README information to a user when desired.  That is pretty
much impossible without this, and that's a shame.  The reason I'm
thinking about it now is that it is relevant for caching.


=== Ideal RubyGems GUI ===

Here is a part of the RubyGems GUI of my dreams.

 * A list of gems in a table with name, version, status [1],
   description, and link to README. [2]

 * README link is blue if the file is cached, grey if not
   cached, and absent if no README is available.

 * Click on README link to open it in a new window.

   * If the README file is not cached, then the client now has to
     get it.  That means asking the RubyGems repository for it,
     which in turn will cache it for later access. [3]
 
[1] Installed, cellared or remote.
[2] There could be other things too, like a link to open RDoc,
    and a button to browse the directory.
[3] As an implementation detail, the only way we can get hold of
    the README at the moment is to download the gem and extract it.
    That gem would therefore become cellared.  We could look at
    making the README available directly from the server, but that
    wouldn't change the repository design much, because it would
    still have to cache the README data.


=== Conclusion ===

Is there support for such a README feature in the gem specification
and in the repository?  Does the above GUI description sound
desirable?  Any other thoughts on the matter?

Cheers,
Gavin