From: Justin Collins <justincollins@...>
Date: 2011-07-19T06:19:22+09:00
Subject: Re: Ruby Readline - and why ruby can learn from python

--------------010009060406040800010807
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

On 07/18/2011 01:02 PM, Marc Heiler wrote:
> 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 ...
>

I know you already wrote a lot, but could you clarify what is better 
about the Python documentation? I looked at the link and the content 
looks extremely similar to the ruby-doc link. There is a brief 
description, some examples, and documentation of the methods.[1] In 
fact, the ruby-doc page appears to have more examples than the Python page.

Thanks,
Justin

(Sidenote: how weird is this?
   ruby-doc: "This module defines a number of methods to facilitate 
completion and accesses input history from the Ruby interpreter"
   python: "The readline module defines a number of functions to 
facilitate completion and reading/writing of history files from the 
Python interpreter." )

[1] To be absolutely clear, I'm talking about 
http://ruby-doc.org/stdlib/libdoc/readline/rdoc/classes/Readline.html 
and http://docs.python.org/library/readline.html)

--------------010009060406040800010807--