----- Original Message -----
From: "Hal E. Fulton" <hal9000 / hypermetrics.com>


> ----- Original Message -----
> From: "stibbs" <stibbs / nothanks.foo.web-hosting.com>
>
> > >
> > > So again, could you give us some _specific_ examples of actual
> >
> > I feel that in my original post i was specific as i could be.
>
> OK, I'm not flaming you. I'm just trying to communicate.
>
> Phil's request is reasonable. And you have *not* been as
> specific as you could be, because you have not named
> even ONE item that needs improved documentation.
>
> > If people
> > here feel that the the overall online english ruby documentation does not
> > need improvement, great.
>
> No one said that! There's a huge need for improvement. But
> there's also a huge amount out there.

It's reasonable then to point the question back at you! ;)  If there's a huge
need for improvement, what's an example?

> OK, I myself will be specific.
>
> Here are (some) things that I think ARE documented
> adequately in English:
>
> 1. Core classes: Array, Bignum, Binding, Class, Continuation,
> Dri, Exception, FalseClass, File, File::Stat, Fixnum, Float,
> Hash, Integer, IO, MatchData, Method, Module, NilClass,
> Numeric, Object, Proc, Range, Regexp, String, Struct,
> Struct::TMS, Symbol, Thread, ThreadGroup, Time, TrueClass
>
> 2. Core modules: Comparable, Enumerable, Errno, FileTest,
> GC, Kernel, Marshal, Math, ObjectSpace, Process
>
> 3. Standard libraries: Complex, Date, English, Find, Ftools,
> Getoptlong, Mkmf, Parsedate, PStore, Tempfile, Mutex,
> ConditionVariable, Timeout, WeakRef
>
> 4. OOP libraries: Visitor, Delegation, Observer
>
> 5. Networking Libraries: BasicSocket, IPSocket, TCPSocket,
> SOCKSSocket, TCPServer, UDPSocket, UNIXSocket, UNIXServer,
> Socket, Net::FTP, Net::HTTP, Net::HTTPResponse, Net::POP,
> Net::APOP, Net::POPMail, Net::SMTP, Net::Telnet, CGI,
> CGI::Session
>
> 6. Other stuff: RDOC, REXML, DRb, eRuby, irb, debug.rb,
> and so on.
>
> Which of these do you consider underdocumented? Or is it
> something else entirely?
>
> Hal
>

Your enumeration of the well-documented aspects of Ruby is correct, IMO.  I've
never had any trouble getting documentation on classes and methods in the
language and its standard libraries.  Well, no more trouble than having to flip
between ri, Pickaxe and Nutshell.

However, if you have a proper Perl installation on your system, take a look at
"man perl".  Apologies for the long post, but here is all the links to other
manpages it contains:

   perl            Perl overview (this section)
   perlfaq         Perl frequently asked questions
   perltoc         Perl documentation table of contents
   perlbook        Perl book information

   perlsyn         Perl syntax
   perldata        Perl data structures
   perlop          Perl operators and precedence
   perlsub         Perl subroutines
   perlfunc        Perl builtin functions
   perlreftut      Perl references short introduction
   perldsc         Perl data structures intro
   perlrequick     Perl regular expressions quick start
   perlpod         Perl plain old documentation
   perlstyle       Perl style guide
   perltrap        Perl traps for the unwary

   perlrun         Perl execution and options
   perldiag        Perl diagnostic messages
   perllexwarn     Perl warnings and their control
   perldebtut      Perl debugging tutorial
   perldebug       Perl debugging

   perlvar         Perl predefined variables
   perllol         Perl data structures: arrays of arrays
   perlopentut     Perl open() tutorial
   perlretut       Perl regular expressions tutorial

   perlre          Perl regular expressions, the rest of the story
   perlref         Perl references, the rest of the story

   perlform        Perl formats

   perlboot        Perl OO tutorial for beginners
   perltoot        Perl OO tutorial, part 1
   perltootc       Perl OO tutorial, part 2
   perlobj         Perl objects
   perlbot         Perl OO tricks and examples
   perltie         Perl objects hidden behind simple variables

   perlipc         Perl interprocess communication
   perlfork        Perl fork() information
   perlnumber      Perl number semantics
   perlthrtut      Perl threads tutorial

   perlport        Perl portability guide
   perllocale      Perl locale support
   perlunicode     Perl unicode support
   perlebcdic      Considerations for running Perl on EBCDIC platforms

   perlsec         Perl security

   perlmod         Perl modules: how they work
   perlmodlib      Perl modules: how to write and use
   perlmodinstall  Perl modules: how to install from CPAN
   perlnewmod      Perl modules: preparing a new module for distribution

   perlfaq1        General Questions About Perl
   perlfaq2        Obtaining and Learning about Perl
   perlfaq3        Programming Tools
   perlfaq4        Data Manipulation
   perlfaq5        Files and Formats
   perlfaq6        Regexes
   perlfaq7        Perl Language Issues
   perlfaq8        System Interaction
   perlfaq9        Networking

   perlcompile     Perl compiler suite intro

   perlembed       Perl ways to embed perl in your C or C++ application
   perldebguts     Perl debugging guts and tips
   perlxstut       Perl XS tutorial
   perlxs          Perl XS application programming interface
   perlclib        Internal replacements for standard C library functions
   perlguts        Perl internal functions for those doing extensions
   perlcall        Perl calling conventions from C
   perlutil        utilities packaged with the Perl distribution
   perlfilter      Perl source filters
   perldbmfilter   Perl DBM filters
   perlapi         Perl API listing (autogenerated)
   perlintern      Perl internal functions (autogenerated)
   perlapio        Perl internal IO abstraction interface
   perltodo        Perl things to do
   perlhack        Perl hackers guide

   perlhist        Perl history records
   perldelta       Perl changes since previous version
   perl5005delta   Perl changes in version 5.005
   perl5004delta   Perl changes in version 5.004

   perlaix         Perl notes for AIX
   perlamiga       Perl notes for Amiga
   perlbs2000      Perl notes for POSIX-BC BS2000
   perlcygwin      Perl notes for Cygwin
   perldos         Perl notes for DOS
   perlepoc        Perl notes for EPOC
   perlhpux        Perl notes for HP-UX
   perlmachten     Perl notes for Power MachTen
   perlmacos       Perl notes for Mac OS (Classic)
   perlmpeix       Perl notes for MPE/iX
   perlos2         Perl notes for OS/2
   perlos390       Perl notes for OS/390
   perlsolaris     Perl notes for Solaris
   perlvmesa       Perl notes for VM/ESA
   perlvms         Perl notes for VMS
   perlvos         Perl notes for Stratus VOS
   perlwin32       Perl notes for Windows

All this information at my fingertips fooled me into believing the language was
more usable than it really was (or at least, than I found it).  It is
definitely a sign of a mature language and user community.

I wonder what other Ruby folk think of this collection of information, whether
there is any sense or feasability in creating some documentation of this kind
for Ruby.  Finding a format to please everybody is difficult: I think man pages
are terrific, but others may not.

Ruby doesn't even *have* a manpage on my system (Cygwin).  A basic manpage
containing links to the online book, ruby-talk, etc. would be a start.

Cheers,
Gavin