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.htmlit can therefore be determined which packages have been installed
and have documentation installedThis 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