Ruby 1.9 Built-in Library--Finished First Pass

One of the scary things about revving the PickAxe for Ruby 1.9 is updating the reference section where I describe all the built-in classes and methods. It involves working through the interpreter source, looking for all the rb_define_method calls (and their friends) and then reading the C implementation of the corresponding methods. Many methods are unchanged from 1.8. But, at the same time, many have changed. Often they take an additional parameter, or return an Enumerator where previously they required a block. Then there are the new classes (something like 6 of them) and new methods. (It looks like there are over 200 new built-in methods in the current Ruby 1.9).

All in all, I count something like 300 [1.9] flags in the new library reference. Some flag stuff is as trivial as a change of a default return type, while others flag entire new classes.

It's incredibly time-consuming work, and I'm constantly grumbling while doing it. But I come out the other end knowing a whole bunch about the library, and with a deeper respect for the folks who maintain it.

Comments

[James Edward Gray II]

We sure appreciate you saving us all of that work. The Pickaxe reference section is the place of the book I visit every single day. Thank for providing such a useful tool!

[iggy]

how complete is the standard library documentation going to be?

while I absolutely love the pickaxe books, the cursory description of some important libraries in chapter 28 of the 2nd Ed is imho a significant weakness of the book. I can't tell you how frustrating it is to look something up, and not find even a listing and signature for the methods in a class.

so please, please, please, fix this..

[Dave Thomas]

Iggy:

It's a compromise: the book is already 900 pages. With Standard Libraries (as opposed to builtins) documented to the every-method level, it would be 1400-1500 pages, which is clearly too big. So I decided to list what they did and show example usage, then rely on folks who were interested to investigate the RDoc and the like.

Dave

[iggy]

Dave,
I'm going to apologize ahead of time, just in case I offend you. I don't mean to, and I do understand the compromises. But I want to make a couple of points, and I may be a little forceful. Please understand, though, I do hold you in high esteem.

First of all, I don't buy for a NY minute the argument that a 1400 page book is excessively long or too big. I have 2 books on my immediate reference shelf, The OpenGL SuperBible 4th Ed and Lutz's Programming Python 2nd Ed books, that are each over 1200 pages long. And both of them are *thumb-worn*.

Same with the argument of built-ins vs. standard library, which to me is a false distinction. The standard library comes with the distribution, and is part of the baseline functionality of the language, in much the same way the C standard library is for the C language (and in Cs case, the standard library is a compulsory part of the language standard). There's *no* difference, in my mind, between the two, except for scoping.

So my argument would be that if it takes 1400 pages to document the standard library, then so be it. If there are mechanical issues associated with printing books of that size, one could split the book into volumes, or figure out a way to make the documentation more compact from a printing point of view (eg 2 column layout, smaller font).

I would point out that the Ruby book landscape has changed since the 1st edition, and that tutorial or language feature coverage information is far more widespread than in the past. Matz and David's new book is spectacularly good in that regard. Consequently, given that the community regards it as the de-facto standard reference, I would suggest that the role of your book may also have evolved in the seven years since the first edition.

Some things are worth doing well, and the documentation of the Ruby Standard Library, imho, falls into that category. I guess I wouldn't be as heated up about the subject, except that there is *no* english language documentation of this kind, anywhere, and given that your book comes the closest to doing that, I see an opportunity in the new edition of your book for that failing in the english language Ruby community to be fixed once and for all.

My frustration stems from the fact that the Python community, for some reason, has no problem in producing complete printable API documentation, in many languages. In fact their documentation is somewhat excessive. But when I have the need to write some Python code, I can take a couple of books and a pad of paper, and go off somewhere quiet and write my code, without an interruption in my workflow or thought process. I can't yet do that with Ruby.

You might argue that there are a lot more Pythonistas than Rubyites in the world, and that's the reason for the disparity, but I think the essential difference is that full printable documentation is a true imperative for the Python community and not for the Ruby community. I'd also point out that's not true for Rails, for which there is an abundance of documentation.

[Dave Thomas]

Iggy:

Not unreasonable, although I'm not sure I totally agree.

I think the PickAxe has two things going for it: it's currently the only book that covers all of 1.9 (the ORA book went to print a trifle early, and so missed new built in classes and other changes to the language). It's also a one-stop shop.

It took me about 9 months to document the built-in libraries. I'd estimate about the same again to to every single public method in the standard library (maybe slightly less, as much of it is written in C, and not Ruby). That's a significant investment. Let me think about it. But, whatever the decision, it won't be able to make it into the current edition.

Dave

[iggy]

Dave,
let me just clarify..

I was trying to suggest, in my clumsy way, that what is needed is a complete language and library reference, and that if one needed to make space, I'd be inclined to sacrifice the tutorial parts of the pickaxe book in service of that goal.

For instance, I'm not sure of the value of covering the Tk library without the concomitant library documentation elsewhere in the book. To me that's just being a tease :)

The point wrt Matz and David's book is that they go into wonderful expositional detail in places and on subjects that could be more compactly expressed in your book. I was not trying to suggest that their book had a more complete coverage of language features.

And I understand the effort it would take to do what I'm suggesting. But it would be so worth it. Maybe a call to arms in the community is what's needed.

[Peter Cooper]

Iggy has, perhaps, better expressed one of my own problems with the Pickaxe. If you had to slot it into a single definition, it's a "reference book" but the temptation to make it a jack of all trades has weakens both the tutorial and reference sections. Ideally, the tutorial could be a lot shorter, and the reference a lot deeper, but, of course, this is a significant amount of work!

One thing you can say about the Pickaxe, however, is that it's consistent with the "pragmatic" goals of the publisher. I am not sure, however, that a book should be pragmatic and generalist, even if a developer should be. There are instances where specialization helps improve quality significantly, and I think a divide between reference and tutorial publications is a prime case of this.

Of course, it's not as if anyone else is bothering to produce an extremely deep reference book on Ruby, so any work you do with Programming Ruby is naturally of great benefit to the community. I just wish people would realize, however, that a "jack of all trades" book is not, and can never be, a "definitive" reference or a definitive tutorial, and that those alternative, specialist titles still need to be produced.

[Dave Thomas]

Peter:

I know you have an agenda wrt the PickAxe, but I also feel you're being somewhat unfair. The PickAxe _is_ the definitive reference to the built in libraries. It runs to over 300 pages, and could be a free-standing book. It's also the only listing of all the standard libraries, with running code examples for each. And, finally, it's an introduction to the language, done in a style different to 90% of the other language books. Some people love that style, others, like you, don't.

Of course, as the author of a tutorial book, you have some skin in this game, too...

[James Edward Gray II]

I've contributed documentation patches for several of the standard libraries and after reading through the code for that, I seriously doubt a method by method reference has much value there. A large chunk of those libraries just aren't designed for public consumption.

ERb is a great example. There are tons of classes, modules, and methods in there, but even an application that integrates with it heavily (Rails, for example) uses under ten of them. That's really the public interface, I guess.

Anyway, I'm not against the idea of a book that covers the standard library. I know I would buy a copy. I'm just saying that what we want out of such a book is probably an expansion of the introductions in the Pickaxe more than an API reference. Hitting the highlights should be helpful enough.

[Rob Mackowick]

Hey, what happened to that post I got in my RSS reader that's entitled "And the winner for the book title"? Can we safely assume your partners at O'Reilly made you take it down?...

[Dave Thomas]

Our partners at O'Reilly have no control whatsoever over what I blog--they're our distributor, and have no input to our business.

I took it down because I realized that it was hurtful to the authors and (having been the target of hurtful blog entries myself) I didn't want it to have that effect.

[iggy]

In response to James' post, what we have right now with the PickAxe book is exactly standard documentation that hits the highlights of the standard libraries, as opposed to the built-ins. And it should be clear that the documentation I'd like to see is limited to the public or semi-public (i.e what the C++ people would call public and protected classes and methods) interfaces, on the basis that I don't need to see or know how a hot dog is made to enjoy one.

However, imho the purpose of a reference book is not just to remind me of the calling signature of a method, but to act as a guide to what those libraries are capable of doing, so there needs to be full coverage of the public and semi-public interfaces, even if it is terse.

I've been programming for over 30 years, and I can't tell you over the course of that time, how many situations where I've had a coding or design problem that was solved because I happened to read the documentation and stumbled across something that either did what I needed or came close. You know, that crystalline "OMG! I didn't realize I could do *this* in ruby!" moment that every Ruby programmer experiences at least once.

To me that's the true value of such a tome.