From: dagbrown@... (Dave Brown)
Date: 2004-01-20T10:40:00+09:00
Subject: Re: Fighting Ruby's bad fame

In article <20040119071041.60609.qmail@web41112.mail.yahoo.com>,
Thomas Adam  <thomas_adam16@yahoo.com> wrote:
:  --- slumos@yahoo.com wrote: 
: 
: [..snip..]
: 
: > It's worth noting that if Perl has "better" documentation, it's
: > because the core Perl people purposely built a community where
: > non-conformism was punished.  The transition from Perl 4 to Perl 5 was
: > marked by anyone asking for help with 4 being told that they should
: > use 5 instead, and anyone announcing a new program being told they
: > should rewrite it as a module instead.  I don't know about anyone
: > else, but my impression of the Perl community at that time was not
: > certainly not that it was friendly.
: 
: You're comparing the two as if they're synonymous -- don't. Ruby is
: evolving, yes. It has not been around nearly so long (ha!) as Perl. The
: documentation is weak, but it is getting better. Miracles do not happen
: overnight.
: 
: Why should we start adopting traits that Perl has? If we did that we might
: as just well switch to perl at the end of the day...

Why should we ignore positive traits that Perl has merely because we
want to be different from Perl?

Perl's POD documentation rules, because it's pretty much always what
you actually wanted.  Compare with Python's documentation--here, I'll
show you what happens when you say "pydoc" on a well-known piece of user
software written in Python:

  [~] pydoc btdownloadcurses
  Help on module btdownloadcurses:

  NAME
      btdownloadcurses

  FILE
      /usr/bin/btdownloadcurses

  DESCRIPTION
      # Written by Henry 'Pi' James
      # see LICENSE.txt for license information

  CLASSES
      CursesDisplayer
      
      class CursesDisplayer
       |  Methods defined here:
       |  
       |  __init__(self, mainerrlist)
       |  
       |  chooseFile(self, default, size, saveas, dir)
       |  
       |  display(self, dict={})
       |  
       |  error(self, errormsg)
       |  
       |  failed(self)
       |  
       |  finished(self)

  FUNCTIONS
      commaize(n)

      fmtsize(n, baseunit=0, padded=1)

      fmttime(n)

      prepare_display()

      run(mainerrlist, params)

      signal(...)
          signal(sig, action) -> action

          Set the action for the given signal.  The action can be SIG_DFL,
          SIG_IGN, or a callable Python object.  The previous action is
          returned.  See getsignal() for possible return values.

  (etc)

Completely worthless for what you most likely WANTED to find out about
the thing, which is, "how do you use it?"  Useful if you're a programmer
perhaps, but why would you want to import a script meant to be run as a
program, as a module?

Let's compare with something from the standard Perl distribution:

  [~] perldoc find2perl
  FIND2PERL(1)          User Contributed Perl Documentation         FIND2PERL(1)



  NAME   
         find2perl - translate find command lines to Perl code

  SYNOPSIS       
                 find2perl [paths] [predicates] | perl

  DESCRIPTION
         find2perl is a little translator to convert find command lines to
         equivalent Perl code.  The resulting code is typically faster than run-
         ning find itself.

         "paths" are a set of paths where find2perl will start its searches and
         "predicates" are taken from the following list.

         "! PREDICATE"
             Negate the sense of the following predicate.  The "!" must be
             passed as a distinct argument, so it may need to be surrounded by
             whitespace and/or quoted from interpretation by the shell using a

But if you do a perldoc on Data::Dumper, which you'll want to use
as a module, you get this:

  NAME   
         Data::Dumper - stringified perl data structures, suitable for both
         printing and "eval"

  SYNOPSIS   
             use Data::Dumper;
             
             # simple procedural interface
             print Dumper($foo, $bar);
             
             # extended usage with names
             print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
             
             # configuration variables
             { 
               local $Data::Dumper::Purity = 1;
               eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
             }

I think that the "documentation follows most common use" feature of Perl
is something to be admired and emulated, not dismissed because of its
ancestry.

--Dave