From: Marc Heiler <shevegen@...>
Date: 2011-07-19T05:02:52+09:00
Subject: Ruby Readline - and why ruby can learn from python

Lately I wanted to have <TAB> completion work for some of my scripts
where I use readline. For some reason, this was easier in bash with the
command "complete" than in pure ruby, and I wondered about this ...

Now then, I looked at Ruby's docu about Readline:

  http://ruby-doc.org/stdlib/libdoc/readline/rdoc/index.html

I guess this is the official docu about Readline.

I make it to the point:

- If you call this "documentation" then you are like tossing cold water
over the face of someone new to ruby.

This is not documentation.

This is really more of a bad, horrible joke. It is so horrible that the
better service to everyone would be to REMOVE the official documentation
and let people google for Readline docu in Ruby. Because this way, they
are likely to find A BETTER DOCUMENTATION (save for the API perhaps, but
you could just display the source).

I did search. I looked around a bit and indeed, there is elegant and
nice documentation about Readline. For example, here:

  http://bogojoker.com/readline/

With explanations and examples.

This should become a standard. It does not contain enough information of
course, but still, it is MUCH MUCH better than the crappy official
documentation.

I am still struggling to find how to EASILY have tab complete working
without getting my head diluted into procs and why I'd need them anyway.
(Yes, the actual example is more complicated than that, but every few
months later I need it, and when I look at the crappy documentation for
Readline I am pulling at my hair.)

I love ruby. From a design point, it is much better than Python.

HOWEVER, please compare the python documentation about Readline:

  http://docs.python.org/library/readline.html

It comes with working examples! It comes bundled in a BIG, FAT "online"
book version. THIS is how documentation should be. Really, this is where
ruby could learn from python.

Even php allows at least user added hints on how to best use this!

Why is the Ruby world stuck in the year 1999 when it comes to
documentation please? Throw rdoc away. Entirely. Remove it. Dismiss it.
Tear it apart. This tool is doing nothing other than giving people the
WRONG idea how to DOCUMENT things.

Look at RoR too:

  http://api.rubyonrails.org/

Sorry, but this is not documentation. This is called a MESS.

It is time to find a better alternative, FOR THE SAKE OF PEOPLE WHO LIVE
IN THE WWW YEAR 2011.

And if you don't want to listen to my rant while I dig painstakingly
into the Readline crap, then please, at least learn from python in how
to properly document stuff. I gave you the link above to python, dig
around and try to understand why python is able to document itself
properly yet ruby fails like a pathetic newbie here.

It's for the better for all of us if the docu becomes better, honestly.

But not in little steps. It is time to make the documentation adhere to
standards that try to look into the future - because right now, rdoc is
stuck in 1999. And in ten years, it will have reached ... the standard
of 2001 ...

-- 
Posted via http://www.ruby-forum.com/.