[Rubygems-developers] "readme" specification and repository support
gsinclair at soyabean.com.au
Sun Jun 6 09:12:07 EDT 2004
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"
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 ,
description, and link to README. 
* 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. 
 Installed, cellared or remote.
 There could be other things too, like a link to open RDoc,
and a button to browse the directory.
 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?
More information about the Rubygems-developers