Suggestions to the Ruby community

ruby-talk
1

Hi, first i would like to state that i absolutely love Ruby more than any
other language i use (perl, python, PHP, javascript, and now ruby). Others
i work with also have taken a look at Ruby and most have the same feeling
about it i do. That being said, we found that there is a huge lack of
english documentation and therefore would consume to much of our time to
learn it and apply it for use in our work.

suggestions:

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

contribute code snippets to pleac.sourceforge.net

in general:

other than documentation, maybe it would be a good idea for people who
also know perl to go through cpan and port the modules that are very
useful to various types of companies.

I can honestly say that if there was the type of documentation available
for ruby that there is for python our company would adopt it, we already
like ruby because from doing a bit of research ruby has more community
contributed modules than python. In my career as being a sys adming and
web development programmer I have noticed is that when companies are
looking to embrace opensource tools they look at the community support
which basically adds up to “how many modules do they have that can be used
in business and how are the docs”. Are project manager even took a liking
to ruby but it was agreed by all of us we can’t use it due to the lack of
thorough documentation on standard modules/classes/methods and also
community contributed ones.

Ruby is a n excellent language, with perl6 taking at least another year or
(and most likely) more and the python community’s focus on what is
obviously hobby projects that seem to be for the most part rebuilding the
wheel 7 times over, you as a community can should take more of a pro-active
approach to pushing ruby onto the general public (average joe programmers)
and companies. The way to do it is through thorough documentation and
modules companies find useful. I suggest following in the style of matz by
grabbing the best from other community’s and applying it to ruby (python
style documentation and the most frequently used modules from cpan).

Please take into consideration my coworkers and myself do know how to use
google and ri, we have found all the documentation and articles that are
out there on ruby, it was pretty much a 2 week long project our dev crew
and project manager did in out spare/off-work time. if anyone is
interested we use apache/perl/mod_perl and sometimes mason or php for
e-commerce systems and python for general sys admining.

I like ruby, this isn’t meant in anyway as a put-down, it is meant to maybe
get some programmers to take more of a pro-active approach to spreading
ruby and think a little bit as a small company would if there were lots of
lazy but big competition in the same field with the idea of taking over
most of the market share within a year or so. Once perl6 is out, if ruby
hasn’t edged it’s way into a bit more companies, this is just an assumption
(and a big one), i think it will be very hard for ruby to pick up steam
in the english speaking countries. “The more people making use of the
language the better!” is a great way to think imo, especially with a
language as beautiful and useful as ruby.

take a pro-active approach! :slight_smile:

best regards,
stibbs

2

Python’s module index? I’m also a Python user, but I’m not sure what
you are referring to.

···

On Fri, Aug 30, 2002 at 07:13:46AM +0900, stibbs wrote:

about it i do. That being said, we found that there is a huge lack of
english documentation and therefore would consume to much of our time to
learn it and apply it for use in our work.

suggestions:

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

–
Matt Gushee
Englewood, Colorado, USA
mgushee@havenrock.com

3

More to the point, someone should get in touch with the CPAN folks.
There’s an open offer to have a ruby section of CPAN, to leverage the
existing infrastructure.

···

At 7:13 AM +0900 8/30/02, stibbs wrote:

english speaking ruby users should get together and copy the idea of
python’s module index.

–
Dan

--------------------------------------“it’s like this”-------------------
Dan Sugalski even samurai
dan@sidhe.org have teddy bears and even
teddy bears get drunk

4

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

What is that? Could you describe it for those of us not that familiar with
Python?

Thanks,

James

5

stibbs wrote:

Hi, first i would like to state that i absolutely love Ruby more than any
other language i use (perl, python, PHP, javascript, and now ruby). Others
i work with also have taken a look at Ruby and most have the same feeling
about it i do. That being said, we found that there is a huge lack of
english documentation and therefore would consume to much of our time to
learn it and apply it for use in our work.

The Ruby book list:

http://www.rubygarden.org/ruby?RubyBookList

lists a considerable number of English-language books. “Programming
Ruby”, the one that most Ruby users consider to be a “must-have”, is
freely available on-line here:

http://www.rubycentral.com/book

It’s also included in the Windows installer for Ruby. Some of the other
books, such as the “Ruby Developer’s Guide”, focus more on contributed
modules for GUI development, database access, XML and web services.

suggestions:

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

Most, if not all, of Ruby’s built-in modules are documented in
“Programming Ruby”. It is true that for some of the contributed modules,
the only available documentation is in Japanese.

Other than documentation, maybe it would be a good idea for people who
also know Perl to go through CPAN and port the modules that are very
useful to various types of companies.

Maybe you could be one of those elusive “people”? The library modules page:

http://www.rubygarden.org/ruby?LibraryModules

serves as one focus for this kind of wish list. And, if you haven’t
already discovered it, the Ruby Application Archive:

http://www.ruby-lang.org/en/raa.html

is the central catalog, so to speak, for contributed Ruby modules.

I can honestly say that if there was the type of documentation available
for Ruby that there is for Python our company would adopt it, we already
like Ruby because from doing a bit of research Ruby has more community
contributed modules than Python. In my career as being a sys admin and
web development programmer I have noticed is that when companies are
looking to embrace open source tools they look at the community support
which basically adds up to “how many modules do they have that can be used
in business and how are the docs”. Our project manager even took a liking
to Ruby but it was agreed by all of us we can’t use it due to the lack of
thorough documentation on standard modules/classes/methods and also
community contributed ones.

You are correct that Ruby’s community is very active and enthusiastic,
and if you can be more specific about which modules, classes or methods
aren’t documented to your satisfaction that would probably help people
point you to the appropriate resources. As I mentioned earlier, there’s
a lot of good English-language documentation available (on-line and
elsewhere).

Ruby is an excellent language, with Perl 6 taking at least another year or
(and most likely) more and the Python community’s focus on what is
obviously hobby projects that seem to be for the most part rebuilding the
wheel 7 times over, you as a community should take more of a proactive
approach to pushing Ruby onto the general public (average joe programmers)
and companies. The way to do it is through thorough documentation and
modules companies find useful. I suggest following in the style of matz by
grabbing the best from other communities and applying it to Ruby (Python
style documentation and the most frequently used modules from CPAN).

As a member of the Ruby community, I hereby appoint you as a fellow
member of the Ruby community. So get to work!

Please take into consideration my co-workers and I do know how to use
google and ri, we have found all the documentation and articles that are
out there on Ruby, it was pretty much a 2 week long project our dev crew
and project manager did in our spare/off-work time.

Interesting. When I do a google search for “ruby”:

http://www.google.com/search?hl=en&ie=UTF-8&oe=UTF-8&q=ruby

the fifth link in the list is the on-line version of “Programming Ruby”.
The eighth link is to the Ruby Garden portal site, which is the source
of most of the other links I’ve quoted.

I like Ruby, this isn’t meant in any way as a put-down, it is meant to maybe
get some programmers to take more of a proactive approach to spreading
Ruby and think a little bit as a small company would if there were lots of
lazy but big competition in the same field with the idea of taking over
most of the market share within a year or so. Once Perl 6 is out, if Ruby
hasn’t edged its way into a bit more companies, this is just an assumption
(and a big one), I think it will be very hard for Ruby to pick up steam
in the English-speaking countries.

Sounds like Perl 6 is two years too late (and counting). Ruby has been
picking up a tremendous amount of “steam” in English-speaking countries
over the last few years; it didn’t just suddenly appear out of thin air
when you heard about it a few weeks ago. Since I’m not a Perl user,
what, specifically, are the new features of Perl 6 that you believe will
cause Ruby to lose steam once Perl 6 is released? That is to say, what
is it that is changing between the currently-available Perl 5.x and Perl
6 that will suddenly nullify the things that have drawn large numbers of
“converts” from the Perl and Python camps?

6

I’ve encountered the same complaints from my co-workers and
colleagues, all of whom came to Ruby from Perl or Python. Many in this
forum have replied to the effect that there is no documentation
problem, and I agree that it’s not as bad as most think it is, but as
they say, “where there’s smoke, there’s fire”.

My boss, to give you an example, nearly pulled out his hair trying to
figure out how to use DBI, because he expected documentation to be
someplace obvious, like ./doc/README, not in lib/dbi/doc/DBI_SPEC. My
point being that while, yes, some external packages are simply devoid
of documentation, in many cases what you’re seeing is not frustration
at the lack of documentation, but at the lack of consistency with
regard to its location, format and presentation.

The problem, to me, is not that Ruby is particularly bad in the
documentation area, but that its competitors are so much better and
more consistent. I can walk through my entire Perl installation
(containing probably over a hundred modules), and type

% perldoc Date::Manip

or whatever, and get reliably complete information about how to use
the module.

I was surprised just now to find that there is no absolute requirement
that you have perldoc to post software on CPAN. If it’s not a
requirement, it is certainly more deeply ingrained in the Perl culture
than it is in Ruby’s. I have never encountered a Perl module that
did not include perldoc. Not even once.

Advantages of perldoc:

o The format is standard, and looks suspiciously like another
format that at least Unix-users are familiar with (manpage
format). Don’t we all immediately lower our opinion of a Unix tool
that doesn’t include a manpage? There’s a reason – manpages are quick,
dense and usually complete; if an option isn’t in the manpage, it
might as well not exist.

o To compare to ‘ri’, it doesn’t uselessly reference
page-numbers in an online resource that is only page-numbered
in the print version. ‘ri’ also cannot hope to keep up with the rate
of growth the RAA is seeing; it documents the core classes & modules
only.

o To compare with ‘rdoc’ (which, by the way, is valuable in its
own right in that it can extract some documentation from code that
includes none), I for one refuse to switch constantly between Emacs
and a web browser. It’s designed for multiple output formats, but the
only one that’s implemented is HTML – and frame-ified HTML, so I
can’t just fire up lynx. I like the output, but I would’ve done
plain-text or *roff before tackling HTML.

With regard to consistency, with Perl (and with Python, I think) there
is one main place to go for documentation (perldoc). It’s part of
Perl; no other download is necessary, no web browser is necessary, and
no spelunking into the module’s source-tree looking for an elusive
README is necessary. We have ri, rdoc, rdtool, and who knows what
else, not to mention the other 25% of Ruby modules whose documentation
lies in ./README, ./lib/thingy/stuff/USAGE, a remote webpage, some
vague examples under ./example, or is in some cases simply
nonexistent.

I’m not one who usually compaigns against choice, but in this case I
would rather the community just picked one embedded doc format, for
better or worse, bundled it with Ruby, and dropped the rest.

One further point on a completely different tack: pointing back at the
original poster and saying “so fix it!”, or just calling them a
useless critic, is a cheap and insulting way to deflect what may be
valuable criticism.

dons flame-resistant suit

Dan

···

–
/^Dan Debertin$/
airboss@nodewarrior.org | Did I sleep a little too late,
www.nodewarrior.org | or am I awake? --Byrne

7

This comment is relevant to this thread, but has no particular place it should
be. Anyway…

I need a temp file. I vaguely remember that Ruby can do temp files. It’s not
in ri, but I wasn’t expecting that because it’s a standard library thing,
rather than a built-in.

PickAxe doesn’t have it for some reason, which surprised me.

I lent “The Ruby Way” to a friend, and I’m sure that discussed it somewhere.

“Ruby in a Nutshell” is at work.

So I’m reading tempfile.rb!

Cheers,
Gavin

···

----- Original Message -----
From: “stibbs” stibbs@nothanks.com
Newsgroups: comp.lang.ruby
To: “ruby-talk ML” ruby-talk@ruby-lang.org
Sent: Friday, August 30, 2002 8:13 AM
Subject: suggestions to the Ruby community

Hi, first i would like to state that i absolutely love Ruby more than any
other language i use (perl, python, PHP, javascript, and now ruby). Others
i work with also have taken a look at Ruby and most have the same feeling
about it i do. That being said, we found that there is a huge lack of
english documentation and therefore would consume to much of our time to
learn it and apply it for use in our work.

suggestions:

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

contribute code snippets to pleac.sourceforge.net

in general:

other than documentation, maybe it would be a good idea for people who
also know perl to go through cpan and port the modules that are very
useful to various types of companies.

I can honestly say that if there was the type of documentation available
for ruby that there is for python our company would adopt it, we already
like ruby because from doing a bit of research ruby has more community
contributed modules than python. In my career as being a sys adming and
web development programmer I have noticed is that when companies are
looking to embrace opensource tools they look at the community support
which basically adds up to “how many modules do they have that can be used
in business and how are the docs”. Are project manager even took a liking
to ruby but it was agreed by all of us we can’t use it due to the lack of
thorough documentation on standard modules/classes/methods and also
community contributed ones.

Ruby is a n excellent language, with perl6 taking at least another year or
(and most likely) more and the python community’s focus on what is
obviously hobby projects that seem to be for the most part rebuilding the
wheel 7 times over, you as a community can should take more of a pro-active
approach to pushing ruby onto the general public (average joe programmers)
and companies. The way to do it is through thorough documentation and
modules companies find useful. I suggest following in the style of matz by
grabbing the best from other community’s and applying it to ruby (python
style documentation and the most frequently used modules from cpan).

Please take into consideration my coworkers and myself do know how to use
google and ri, we have found all the documentation and articles that are
out there on ruby, it was pretty much a 2 week long project our dev crew
and project manager did in out spare/off-work time. if anyone is
interested we use apache/perl/mod_perl and sometimes mason or php for
e-commerce systems and python for general sys admining.

I like ruby, this isn’t meant in anyway as a put-down, it is meant to maybe
get some programmers to take more of a pro-active approach to spreading
ruby and think a little bit as a small company would if there were lots of
lazy but big competition in the same field with the idea of taking over
most of the market share within a year or so. Once perl6 is out, if ruby
hasn’t edged it’s way into a bit more companies, this is just an assumption
(and a big one), i think it will be very hard for ruby to pick up steam
in the english speaking countries. “The more people making use of the
language the better!” is a great way to think imo, especially with a
language as beautiful and useful as ruby.

take a pro-active approach! :slight_smile:

best regards,
stibbs

8

http://www.python.org/doc/current/modindex.html

sorry for not being more specific.

···

On Thu, 29 Aug 2002 19:28:28 -0400, Matt Gushee wrote:

On Fri, Aug 30, 2002 at 07:13:46AM +0900, stibbs wrote:

about it i do. That being said, we found that there is a huge lack of
english documentation and therefore would consume to much of our time
to learn it and apply it for use in our work.

suggestions:

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

Python’s module index? I’m also a Python user, but I’m not sure what you
are referring to.

9

english speaking ruby users should get together and copy the idea of
python’s module index.

Python’s module index? I’m also a Python user, but I’m not sure what you
are referring to.

http://www.python.org/doc/current/modindex.html

Oh, that module index. I thought you meant something else.

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

What is that? Could you describe it for those of us not that familiar with
Python?

It’s really just a simple index that allows you to look up any of
Python’s standard library modules by name. Since there are a lot of
modules, it’s very helpful when you have an idea what you’re looking for
but forget what part of the documentation it lives in.

In Python, BTW, a ‘module’ is roughly equivalent to a ‘library’ (?) in
Ruby. It corresponds to one source code file, and contains one or more
class and/or function definitions.

Python has no direct equivalent to a Ruby module.

···

On Fri, Aug 30, 2002 at 07:53:51AM +0900, stibbs wrote:
On Fri, Aug 30, 2002 at 07:56:22AM +0900, JamesBritt wrote:

–
Matt Gushee
Englewood, Colorado, USA
mgushee@havenrock.com

10

Lyle Johnson graced us by uttering:

That is to say, what is it that is changing between the
currently-available Perl 5.x and Perl 6 that will suddenly
nullify the things that have drawn large numbers of “converts”
from the Perl and Python camps?

Between the paragraphs at the bottom of this page and the links
made available there, there should be a good base of information
on Perl6 and how it differs from its predecessor.

http://dev.perl.org/perl6/architecture

Perl6 looks like a totally different animal, but still with that
distinctive Camel aroma.

I don’t have any intention of switching from Ruby, but having
come from Perl, I admit I’m quite interested in where this is
going.

Tim Hammerquist

···

–
How do I type “for i in *.dvi do xdvi i done” in a GUI?
– discussion in comp.os.linux.misc

11

stibbs wrote:

Hi, first i would like to state that i absolutely love Ruby more than
any other language i use (perl, python, PHP, javascript, and now ruby).
Others i work with also have taken a look at Ruby and most have the same
feeling about it i do. That being said, we found that there is a huge
lack of english documentation and therefore would consume to much of our
time to learn it and apply it for use in our work.

The Ruby book list:

http://www.rubygarden.org/ruby?RubyBookList

lists a considerable number of English-language books. “Programming
Ruby”, the one that most Ruby users consider to be a “must-have”, is
freely available on-line here:

http://www.rubycentral.com/book

It’s also included in the Windows installer for Ruby. Some of the other
books, such as the “Ruby Developer’s Guide”, focus more on contributed
modules for GUI development, database access, XML and web services.

Not to sound rude, but as i stated in my first post “Please take into
considera tion my co-workers and I do know how to use
google and ri, we have found all the documentation and articles that are
out there on Ruby.” We have read through the Documentation and online
books you refer to in this post, we also know about the dead-tree books that
are out there on Ruby. I am sharing our overall point of view with
the community after having done some thorough research. It’s an opinion
and we all know what opinions are comparable to, so take it or leave it.

suggestions:

Documentation:

english speaking ruby users should get together and copy the idea of
python’s module index.

Most, if not all, of Ruby’s built-in modules are documented in
“Programming Ruby”.

see above

It is true that for some of the contributed modules,
the only available documentation is in Japanese.

Other than documentation, maybe it would be a good idea for people who
also know Perl to go through CPAN and port the modules that are very
useful to various types of companies.

Maybe you could be one of those elusive “people”? The library modules
page:

http://www.rubygarden.org/ruby?LibraryModules

been there

serves as one focus for this kind of wish list. And, if you haven’t
already discovered it, the Ruby Application Archive:

http://www.ruby-lang.org/en/raa.html

is the central catalog, so to speak, for contributed Ruby modules.

been there also

I can honestly say that if there was the type of documentation available
for Ruby that there is for Python our company would adopt it, we already
like Ruby because from doing a bit of research Ruby has more community
contributed modules than Python. In my career as being a sys admin and
web development programmer I have noticed is that when companies are
looking to embrace open source tools they look at the community support
which basically adds up to “how many modules do they have that can be
used in business and how are the docs”. Our project manager even took a
liking to Ruby but it was agreed by all of us we can’t use it due to the
lack of thorough documentation on standard modules/classes/methods and
also community contributed ones.

You are correct that Ruby’s community is very active and enthusiastic,
and if you can be more specific about which modules, classes or methods
aren’t documented to your satisfaction that would probably help people
point you to the appropriate resources.

to make it easy, how about 97% of them (and yes, i think
i’m very close with that percentage), my original post was a broad
generalization of all the documentation of all the modules and ruby in
general. All you have to do is look at the english documentation on the
modules to see that they are severely lacking in thorough explanation of
their use and methods.

As I mentioned earlier, there’s
a lot of good English-language documentation available (on-line and
elsewhere).

Ruby is an excellent language, with Perl 6 taking at least another year
or (and most likely) more and the Python community’s focus on what is
obviously hobby projects that seem to be for the most part rebuilding
the wheel 7 times over, you as a community should take more of a
proactive approach to pushing Ruby onto the general public (average joe
programmers) and companies. The way to do it is through thorough
documentation and modules companies find useful. I suggest following in
the style of matz by grabbing the best from other communities and
applying it to Ruby (Python style documentation and the most frequently
used modules from CPAN).

As a member of the Ruby community, I hereby appoint you as a fellow
member of the Ruby community. So get to work!

That’s great, but i actually have a side project that has nothing to do with
ruby but does have to do on feeding information to a specific community on
open-source and linux related issues and it consumes most of my spare
time. With my original post i was hoping to convince people without a
side project but looking for one to think about documentation and/or porting
modules. I’m also not trying to dictate what people should do for their
projects, but sometimes in order to really help or make a difference you
might not want to make the 99th wiki wiki clone just for something to do.
My side project lost it’s fun very quick within the first year it starte.
2 years later i am still doing it because i realize there is a need for it
and it makes a real difference to the specific community it targets.

Please take into consideration my co-workers and I do know how to use
google and ri, we have found all the documentation and articles that are
out there on Ruby, it was pretty much a 2 week long project our dev crew
and project manager did in our spare/off-work time.

Interesting. When I do a google search for “ruby”:

http://www.google.com/search?hl=en&ie=UTF-8&oe=UTF-8&q=ruby

the fifth link in the list is the on-line version of “Programming Ruby”.
The eighth link is to the Ruby Garden portal site, which is the source
of most of the other links I’ve quoted.

as i mentioned before, i’ve read through it and so have my coworkers.

I like Ruby, this isn’t meant in any way as a put-down, it is meant to
maybe get some programmers to take more of a proactive approach to
spreading Ruby and think a little bit as a small company would if there
were lots of lazy but big competition in the same field with the idea of
taking over most of the market share within a year or so. Once Perl 6 is
out, if Ruby hasn’t edged its way into a bit more companies, this is
just an assumption (and a big one), I think it will be very hard for
Ruby to pick up steam in the English-speaking countries.

Sounds like Perl 6 is two years too late (and counting). Ruby has been
picking up a tremendous amount of “steam” in English-speaking countries
over the last few years; it didn’t just suddenly appear out of thin air
when you heard about it a few weeks ago.

“it was pretty much a 2 week long project our dev crew and project manager
did in our spare/off-work time.” means exactly what it states and nothing
more. It was a 2 week long unofficial project to consider using ruby as one
of our tools. I have known of ruby for atleast a year and a half and
have played with it off and one since then, also, my coworkers except for
our project manager have been hip to ruby for a while since we have fairly
good personal relations with each other (AKA when i like something such
as ruby i bring it up at work periodically) but i don’t think they have really
toyed with it much until now.

Since I’m not a Perl user,
what, specifically, are the new features of Perl 6 that you believe will
cause Ruby to lose steam once Perl 6 is released?
real OO
That is to say, what
is it that is changing between the currently-available Perl 5.x and Perl
6 that will suddenly nullify the things that have drawn large numbers of
“converts” from the Perl and Python camps?
Every person that i know of who “converted” to ruby has since long converted
back to using python as their main language due to the documentation issue,
and i have quite a few online friends i have kept in contact with for quite some
years that did this. And i find most people that i know do like perl but
they use python for the more clean/realistic OO. I think that rather than
read through my original post and look at what you can pick apart about
it, it might be a good idea to just try and see where i might be coming
from. Judging from your reply to my original post, it seems you assume
i’m just some newbie who has been looking at ruby for a few days and
didnt put much effort in finding what online documentation is actually
available for ruby (even though i stated the opposite in my original post).

Cheers,
Stibbs

···

On Thu, 29 Aug 2002 20:12:24 -0400, Lyle Johnson wrote:

12

o To compare with 'rdoc' (which, by the way, is valuable in its
own right in that it can extract _some_ documentation from code that
includes none), I for one refuse to switch constantly between Emacs
and a web browser. It's designed for multiple output formats, but the
only one that's implemented is HTML -- and frame-ified HTML, so I

   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

pigeon% rd2 -rrd/rd2man-lib hashlike.rd | nroff -man | less
hashlike.rd(1) hashlike.rd(1)

Acces Methods
       These are the common methods for BDB::Btree, BDB::Hash,
       BDB::Recno and BDB::Queue

       o Class Methods

       o Methods

       o Methods specific to BDB::Recno and BDB::Queue

Class Methods
       open(name = nil, subname = nil, flags = 0, mode = 0,
       options = {})

       create(name = nil, subname = nil, flags = 0, mode = 0,
       options = {})

       new(name = nil, subname = nil, flags = 0, mode = 0,
       options = {})
              open the database

       name The argument name is used as the name of a single
              physical file on disk that will be used to back the
              database.

pigeon%

Guy Decoux

13

My boss, to give you an example, nearly pulled out his hair trying to
figure out how to use DBI, because he expected documentation to be
someplace obvious, like ./doc/README, not in lib/dbi/doc/DBI_SPEC. My
point being that while, yes, some external packages are simply devoid
of documentation, in many cases what you’re seeing is not frustration
at the lack of documentation, but at the lack of consistency with
regard to its location, format and presentation.

This is just a thought, but, Python has a standard (discussed in this forum
some time back) that if there’s a string before the first executable line of
code in a class then it’s intended to contain some documentation about that
class.

For example (recast as Ruby, because I can’t remember enough Python) …

class Fred
“”“class Fred is just an example”“”

  def initialize
      # The constructor for Fred
  end

end

In Python, one can get at these strings by doing things like …

print Fred.doc

(Yes, I hate all those undescores, too !!)

To allow Ruby authors some freedom in where they put their documentation,
could we not define a convention that a class has a “doc” method (personally,
I’d prefer to spell it out and say “documentation”, but I’m sure others would
prefer the brevity of “doc”) that returns a String?

Then, each author could code that method any way they like. Eg, it could just
return a constant string, a la Python …

class Fred
def doc
“Class Fred is just an example”
end

 def initialize
    # ...
 end

end

The string returned could, for example, be a URL where the user can find the
documentation. Or doc() could do something more complex, like return the
contents of a file …

class Fred
def doc
File.new(“some/path/Fred.doc”).readlines.flatten
end
end

We could have Object define some kind of generic version that just explains
that this particular entity doesn’t seem to have its own documentation,
giving some suggestions on where to try looking for it.

I’m sure other, more Ruby-fluent people will think of ways to make this more
usable. I’m just throwing this into the mix, to see if it sparks any cool
ideas.

For example, we could have a standard tool, similar to ri, that when given the
name of a class/module, would go off and call doc() and print what was
returned. If doc() wasn’t defined, it could pass the request on to ri, or go
looking for some rd or rdoc information.

For that matter, it could both print what doc() returns and call ri to see
what’s there.

Anyway, just an idea.

Harry O.

14

Try the online pick-axe book.

Jim

···

On Sun, Sep 01, 2002 at 08:36:54PM +0900, Gavin Sinclair wrote:

This comment is relevant to this thread, but has no particular place it should
be. Anyway…

I need a temp file. I vaguely remember that Ruby can do temp files. It’s not
in ri, but I wasn’t expecting that because it’s a standard library thing,
rather than a built-in.

PickAxe doesn’t have it for some reason, which surprised me.

I lent “The Ruby Way” to a friend, and I’m sure that discussed it somewhere.

“Ruby in a Nutshell” is at work.

So I’m reading tempfile.rb!

–
Jim Freeze
If only I had something clever to say for my comment…
~

15

The HTML has it in lib_standard.html.

Massimiliano

···

On Sun, Sep 01, 2002 at 08:36:54PM +0900, Gavin Sinclair wrote:

PickAxe doesn’t have it for some reason, which surprised me.

16

In article 87bs7j6l46.wl@discus.nodewarrior.org,

I’ve encountered the same complaints from my co-workers and
colleagues, all of whom came to Ruby from Perl or Python. Many in this
forum have replied to the effect that there is no documentation
problem, and I agree that it’s not as bad as most think it is, but as
they say, “where there’s smoke, there’s fire”.

My boss, to give you an example, nearly pulled out his hair trying to
figure out how to use DBI, because he expected documentation to be
someplace obvious, like ./doc/README, not in lib/dbi/doc/DBI_SPEC. My
point being that while, yes, some external packages are simply devoid
of documentation, in many cases what you’re seeing is not frustration
at the lack of documentation, but at the lack of consistency with
regard to its location, format and presentation.

The problem, to me, is not that Ruby is particularly bad in the
documentation area, but that its competitors are so much better and
more consistent. I can walk through my entire Perl installation
(containing probably over a hundred modules), and type

% perldoc Date::Manip

or whatever, and get reliably complete information about how to use
the module.

I was surprised just now to find that there is no absolute requirement
that you have perldoc to post software on CPAN. If it’s not a
requirement, it is certainly more deeply ingrained in the Perl culture
than it is in Ruby’s. I have never encountered a Perl module that
did not include perldoc. Not even once.

    • You haven’t been doing Perl very long then. It took YEARS to
      get everybody to write perldoc and it didn’t really take hold
      until CPAN was created and perldoc was distributed with the
      core perl distribution.
    • At least in the US Ruby is still in very early development and
      there are very few people actually working ON it rather than
      with it. To take examples from the history of Perl, for a very
      long time the only documentation was the man page. Perl was in
      use for a long time before the Book[1] appeared. Much like the
      state of Ruby today. Perl documentation really didn’t
      standardize until the CGI boom of the late 90’s. What happened
      was that being a module author created so much demand for
      answers, that a standard documentation system was created
      in self-defense. In the long run it’s much easier to write
      it once than deal with thousands of emails.
    • For it’s stage Ruby has some pretty amazing online
      documentation, but it has no real documentors. It has book
      authors ( which is a very good thing), but nobody committed to
      the dirty thankless task of documentation management.
    • Expecting the current developers to take on this project is
      unrealistic. There have been a couple abortive “Ruby
      Documentation Projects” already and I suspect we will see
      a couple more before the demand is truly there. Ruby has
      it’s “Larry Wall”, we need a “Tom Christiansen”.
    • IMHO, the Ruby document debate is focused a bit too much on
      the tools and format[1] and not on the quality and quantity.
      Rdoc is a great “tool”, but it’s not documentation. Just
      write it and worry about the format later…
    • Booker C. Bense

[1]- this is entirely to be expected, after all we are
programmers and earn our livings with the delusion that
if the tool is just good enough the problem will be solved.

···

Dan Debertin airboss@nodewarrior.org wrote:

17

stibbs graced us by uttering:

That is to say, what is it that is changing between the
currently-available Perl 5.x and Perl 6 that will suddenly
nullify the things that have drawn large numbers of
“converts” from the Perl and Python camps?

Every person that i know of who “converted” to ruby has since
long converted back to using python as their main language due
to the documentation issue, and i have quite a few online
friends i have kept in contact with for quite some years that
did this.

THAT won’t happen.

I’m sorry, but if Ruby ever went downhill (God forbid!), I’m
goin’ back to Perl. If there was ever a language that made it
difficult to do some of the simplest things imaginable, well,
it’s Java. But after that, it’s Python. :wink:

And i find most people that i know do like perl but
they use python for the more clean/realistic OO.

I’ve started to use Ruby for general system scripting in addition
to larger projects.

I think that rather than read through my original post and look
at what you can pick apart about it, it might be a good idea to
just try and see where i might be coming from. Judging from
your reply to my original post, it seems you assume i’m just
some newbie who has been looking at ruby for a few days and
didnt put much effort in finding what online documentation is
actually available for ruby (even though i stated the opposite
in my original post).

As far as taking you for a newbie, you asked the same exact
question most newbies who don’t know how to use Google or ri
would ask. It was most likely a mistake, and it certainly wasn’t
personal.

I think that rather than simply criticizing the community’s
efforts so harshly, it might be a good idea to offer to aid in
the documentation, especially since Ruby and her documention is
an open source endeavour relying on volunteers rather than
complaints. Feedback is always important, but people can only do
so much for free.

Would you be willing to help a more detailed documentation
project? Obviously we can’t develop a doc project equivalent to
Perl’s perldoc overnight, but it can happen with enough hard
work. Do you have enough free time from your job to help in this
regard?

Tim Hammerquist

···

–
relaxen und watchen das AOLerchatten.

18

In article pan.2002.07.31.02.21.23.199006.6766@nothanks.com,

stibbs wrote:

Hi, first i would like to state that i absolutely love Ruby more than
any other language i use (perl, python, PHP, javascript, and now ruby).
Others i work with also have taken a look at Ruby and most have the same
feeling about it i do. That being said, we found that there is a huge
lack of english documentation and therefore would consume to much of our
time to learn it and apply it for use in our work.

The Ruby book list:

http://www.rubygarden.org/ruby?RubyBookList

lists a considerable number of English-language books. “Programming
Ruby”, the one that most Ruby users consider to be a “must-have”, is
freely available on-line here:

http://www.rubycentral.com/book

It’s also included in the Windows installer for Ruby. Some of the other
books, such as the “Ruby Developer’s Guide”, focus more on contributed
modules for GUI development, database access, XML and web services.

Not to sound rude, but as i stated in my first post “Please take into
considera tion my co-workers and I do know how to use
google and ri, we have found all the documentation and articles that are
out there on Ruby.” We have read through the Documentation and online
books you refer to in this post, we also know about the dead-tree books that
are out there on Ruby. I am sharing our overall point of view with
the community after having done some thorough research. It’s an opinion
and we all know what opinions are comparable to, so take it or leave it.

OK, so what kinds of topics should future Ruby books (of either the
dead-tree or online variety) cover that are not covered (or only
superficially covered) in current Ruby books?

I can think of a few topics that might make good articles or perhaps
chapters in a book:

  • Ruby and SWIG (although this is covered somewhat in the Ruby Developer’s
    Guide it would be nice to have a more in-depth treatment)
  • REXML (perhaps a whole Ruby and XML book would be in order, I believe
    Perl and Python both have similar books)

I’m sure there are others, what else?

Most, if not all, of Ruby’s built-in modules are documented in
“Programming Ruby”.

is it that is changing between the currently-available Perl 5.x and Perl
6 that will suddenly nullify the things that have drawn large numbers of
“converts” from the Perl and Python camps?
Every person that i know of who “converted” to ruby has since long converted
back to using python as their main language due to the documentation issue,
and i have quite a few online friends i have kept in contact with for quite some
years that did this. And i find most people that i know do like perl but
they use python for the more clean/realistic OO. I think that rather than
read through my original post and look at what you can pick apart about
it, it might be a good idea to just try and see where i might be coming
from. Judging from your reply to my original post, it seems you assume
i’m just some newbie who has been looking at ruby for a few days and
didnt put much effort in finding what online documentation is actually
available for ruby (even though i stated the opposite in my original post).

So again, could you give us some specific examples of actual
documentation you would like to see for Ruby that doesn’t currently exist?
This could help us prioritize. I’ve done a good bit of Ruby programming in
the last couple of years and I’ve seen the documentation situation
improve greatly during that time, however I’m sure there is still room for
improvement. Also, please consider this newsgroup as a source of
information as well - you’ll find that answers come pretty quickly here.

Phil

···

stibbs stibbs@nothanks.com wrote:

On Thu, 29 Aug 2002 20:12:24 -0400, Lyle Johnson wrote:

19

general. All you have to do is look at the english documentation on the
modules to see that they are severely lacking in thorough explanation of
their use and methods.

There is a french expression for this

   La critique est aisee mais l'art est difficile

Feel free to translate it in "anglois" if someone want to do it.

Sorry,

Guy Decoux

20

o To compare with ‘rdoc’
^^^^^^^^^^^^^^^^^^^^^

pigeon% rd2 -rrd/rd2man-lib hashlike.rd | nroff -man | less
hashlike.rd(1) hashlike.rd(1)

[…etc…]

I was referring to rdoc, not rd. It’s nice to see that rd can do
this, though.

But to use the same exasperating technique of quoting a command as if
it were self-explanatory:

senator% rd2 -rrd/rd2man-lib hashlike.rd | nroff -man | less
ksh: rd2: not found

:slight_smile:

Care to venture a guess as to how many Ruby modules use RD, vs. those
that use rdoc, an ordinary README, or nothing at all? My point is that
the more spread out ruby is with regard to doc formats, the less
useful tools like RD and rdoc are.

Dan

···

At Sun, 1 Sep 2002 01:55:33 +0900, ts wrote:

/^Dan Debertin$/
airboss@nodewarrior.org | Did I sleep a little too late,
www.nodewarrior.org | or am I awake? --Byrne