Ruby Readline - and why ruby can learn from python

Ruby
1

Lately I wanted to have 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:

readline — GNU readline interface — Python 3.11.4 documentation

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 …

2

On 07/18/2011 01:02 PM, Marc H. wrote:

I make it to the point:
you could just display the source).
documentation.

Tear it apart. This tool is doing nothing other than giving people the

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 readline — GNU readline interface — Python 3.11.4 documentation)

3

Hi Marc,

I really had to smile benignly when I read your post.

On 18.07.2011 22:02, Marc H. wrote:

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/

I compared this page with the official docs. I discovered content-wise
that the docs were pretty much matching except the completion part. I’ve
made a patch for the docs including these parts:

https://github.com/mfn/ruby/commit/ae1bea694d5ee1852cfce3c2c2b42155952bd900

When I generate the docs from it, it looks like this
http://i.imgur.com/e7U5G.png . Ugh. The headings don’t suit well and the
source code has no highlighting (in case your wonder: that’s FF 5 with
150% full-page zoom).

But some of the existing ones in this module don’t look much better,
e.g. http://i.imgur.com/SZ2k9.png . Hmm.

Well, the problem as I see it is that tutorial-like examples, when you
have quite some of them, don’t really fit well within a discrete method
documentation. It makes it hard for the developer to discover. IMHO all
the examples from Readline.readline and what I’ve added should be moved
out either into the README or into the Readline module description and
the actual method documentations should be made more slim. But who to
make a call for anything here?

HOWEVER, please compare the python documentation about Readline:
[…]
Even php allows at least user added hints on how to best use this!

I’ve been actively following PHP community a few years ago. I don’t know
much about the python community, but my impression is that the # of
contributors to the project, documentation wise, is like this:

PHP > ruby

I.e. the PHP community has a lot of driving force behind the
documentation team. Just compare MARC: Mailing list ARChives with
http://news.gmane.org/gmane.comp.lang.ruby.documentation (ruby-doc: 3
messages in July, with one unsubscription → PHP: 70 (!) and counting.

Another thing I noticed: a lot of times it looked to me that most ruby
developers use method-centric approach to document things in the
ruby-world which, as I reasoned above, doesn’t suit well for fluent
readable documentation (but maybe I looked at the wrong docs).

I know that PHP has quite a different approach, using docbook and only
parsing the prototype information from the sources, matching with
docbook and doing everything else there. But the reason mustn’t be
necessarily docbook; it’s how they approach to write the documentation.

I took the time and integrated the example because “I’ve been there done
that”: in the open source world, I’ve not seen often coming something
practically out of a complaint :wink: [don’t take that tooseriously, I’m
not criticizing your for your post; by doing that patch I provided
evidence for a counter-example anyway]

  • Markus
4

On 18.07.2011 23:19, Justin C. wrote:

[1] To be absolutely clear, I’m talking about
http://ruby-doc.org/stdlib/libdoc/readline/rdoc/classes/Readline.html
and readline — GNU readline interface — Python 3.11.4 documentation)

Any noticed this?

https://github.com/ruby/ruby/blob/trunk/ext/readline/README
vs
https://github.com/ruby/ruby/blob/trunk/ext/readline/README.ja

I can’t read any of it except the ruby bits, but it looks like it
contains helluva more information.

  • Markus
5

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?

Only the idiots that run the ruby world can answer that. My favorite
ruby documentation trick is when a ruby method gives a link to another
method for the docs, and then the other method gives a link back to the
method you are trying to get information about. Nice and succinct!

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.

Here, here! I think php sets the documentation standard for all other
languages. The user comments are invaluable.

python’s docs are much, much better than ruby’s–but not as good as
php’s. It’s been a few years now, but as I remember Java had very good
docs.

When I am looking for ruby docs, and I conjure up a page with rdoc on
it, I shudder and look away.

6

If you’d like to help make Ruby’s documentation better, it’s actually
really easy!

http://blog.steveklabnik.com/2011/05/10/contributing-to-ruby-s-documentation.html

We’re actually undergoing a documentation drive to chip in and help
make 1.9.3’s documentation the best yet, and I’m sure that better
documentation for Readline would get merged in if you’d contribute
some.