From: "Berger, Daniel" <djberge@...>
Date: 2003-01-24T00:03:47+09:00
Subject: Re: Can we attack the 'not enough libraries' thing straight on?

> > this is one idea CPAN lacks - a central set of standards 
> which modules 
> > must conform to (unit testing for modules?) and a way to 
> separte the 
> > really good modules from all the chatter and useless crap...
> 
> Good ideas.  It's great to have a repository that anybody can 
> contribute to, and we do need to be able know which ones are 
> well implemented and supported.  I wish someone who has used 
> a lot of packages (i.e. not me) would write a summary of 
> packages they think are ready for the big time.  Also along 
> these lines, I believe the RAA should mandate a standard for 
> versioning.  Everything should be versioned x.y.z, with 
> perhaps some allowance for alpha, beta, whatever.  Version 
> numbers based on dates or descriptions are not particularly 
> informative.
> 
> About "standard docs", I think this is the way forward:
>  - packages have a doc directory
>  - this gets installed along with the package so it ends up in
>    something like
>           site_ruby/1.6/froboz/doc/package.info
>                                   /index.html
>                                  
>  - it can therefore be determined which packages have been installed
>    and have documentation installed
> 
> This allows different programs to programatically access all 
> package documentation.  The particular program I have in mind 
> might be called 'rdb' (for Ruby Documentation Browser) and 
> would do the following:
>   - build a list of all installed package doco (using package.info for
>     description etc.)
>   - generate an HTML page containing links to all available package
>     doco (the index.html files, which represent RDoc output and
>     contain the README etc. as well as the API doc)
>   - open a browser to that page
> 
> There you have it.  One command to access all of your 
> available package documentation.  Of course it can take an 
> argument so you can access a particular package doco easily.
> 
> I mention this in this thread because I have a suspicion that 
> Ruby's reputation for a lack of libraries is superficial.  
> There are a lot of libraries; we just don't always access 
> them very well.  Setting some standards and easing access are 
> easy things to do, and they can only encourage effort in 
> creating more high-quality libraries, and higher quality 
> documentation for those libraries.
> 
> One technical nit: not all libraries conform to the pattern 
> whereby they install in a single directory.

A few of us here in Denver are working on this issue.  See
http://development.faeriemud.org/ModuleBuilder/.  There's a link to CVS as
well.

As far as standards, here is how the file layout is gonna be until someone
threatens me with a pair of pliers and a blowtorch (or Michael and Martin
kick me off the project):

Layout will be based on package name.  A script (ala h2xs, but with a better
name and no assumptions that C is present) will be provided to autogenerate
the directory & file layout.  The initial version of this script is called
"rbuildmaker.rb" (name subject to change) and can be found under the bin
directory on the cvs page (follow the links from the url provided above).

Examples:

package "foo" - all package names will be lower case

foo/
   lib/       - foo.rb (plus whatever other libs)
   doc/       - documentation
   test/      - test cases here
   CHANGES    - changelog
   install.rb - a revamped, consistent, standard install script
   MANIFEST   - listing of package contents
   test.rb    - will run any unit tests included (for a "make test", or the
like)
   INSTALL    - installation instructions
   LICENSE    - Licensing information (perhaps relegated to rd2)

package "foo-bar"

foo-bar/
   lib/foo/bar.rb
   ...

In the second example, bar.rb would then be installed in the sitelibdir (by
default - would be configurable) under the directory "foo".  My feeling is
that documentation should be as well (if provided).  I wouldn't mind
autogenerating and installing ri docs or man pages either.  Keeping
everything in the sitelibdir would also make it easier to determine what 3rd
party modules have been installed on your system.  I can't think of a reason
not to install in the sitelibdir, unless it's a permissions/administration
issue.

Some stub documenation will be automatically created for you as well.  For
example, using the foo-bar package, the bar.rb file will start off like
this:

module Foo
   class Bar
      VERSION = "0.1.0"
      # Add code here
      def self.VERSION
         VERSION
      end
   end
end
=begin
= Description
   # Add description
= Synopsis
   # Add synopsis
= Class Methods
   # Add class method docs
= Instance Methods
   # Add instance method docs
= Constants
   # Add constant docs
= Author
   # Your name, email address, irc nick, whatever
= License
   # Ruby's by default.  Change as desired.
= Copyright
   (C) #{current-year} All Rights Reserved.  Change as desired
=end

Thus, package name matches directory layout matches module-class hierarchy.

A couple of points to head off questions:

lower case - You can make your package name whatever case you like, but all
of *mine* are going to be lower case.  Most people seem to follow this
tradition anyway.  Let's make it a standard.

stub - don't bug me about the stub documentation details.  It's JUST STUB
DOCUMENTATION.  I don't expect it to survive long.  It's just there as a
guideline and to remind you to document certain things, like your License
and Copyright.

rd2 - if you prefer rdoc, delete and retype as you see fit.  See my point
about "stub" above.

hypocrisy - I admit I do not follow these standards 100% in my own packages
(but I'm close).  However, I plan on converting all them where they differ
eventually.

Now, autogenerating a file layout is easy.  It's the install.rb script
that's going to be the heart of this project (and thus most difficult).

Questions anyone?

Regards,

Dan