Need some advice on PickAxe II

ruby-talk
1

Folks:

It’s looking as if we’re moving towards agreement with Addison Wesley
on getting the rights to Programming Ruby back. This means that we’ll
be able to produce an updated version, covering Ruby 1.8. No promises:
we still don’t have all the signed agreements, but AW is certainly
being very helpful so far.

Now… I have a question. When it came to documenting the library that
comes with Ruby (the stuff in lib/ and ext/), the original PickAxe
trying to document every method in a subset of the 1.6 distribution: we
picked the library classes and modules that looked as if they were
being used.

In Ruby 1.8, the library has grown astonishingly: I count almost 100
library modules and classes in lib/ alone. If we were to document these
in any kind of detail, the book would grow to 2000 pages, and we
wouldn’t be done until 2008 :slight_smile:

At the same time, the ruby-doc folks are making significant inroads in
adding documentation the library itself: this is available both through
ri and as HTML (at ruby-doc.org, for example).

So, this is what I’m thinking. Rather than document all the methods in
all the lib/ and ext/ classes and modules, I’d like to have a one-page
summary for each. Each page would contain a synopsis of the function of
the library, along with a small number of samples of use. The idea is
that you can read through this to find libraries that would be useful,
and then consult the RDoc for details. Think of it as a kind of
exhaustive library cookbook. I’ve posted sample pages at

http://www.pragmaticprogrammer.com/extracts/sl.pdf

(These are rough, and contain typesetting problems and other errors—I
just wanted to give folks a feel for what I was talking about).

So, here’s the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to
the online or local documentation for the details? (Don’t worry about
the built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

Cheers

Dave

2

I think the original Pickaxe library section was so useful mostly
because the ruby docs were so absolutely lacking. Given good online docs
in html and ri, I don't think I'd want the pickaxe2 to redocument these.

Aside: a nitpick, the organization, alphabetical within 5 chapters, is
maddening. Its the only thing about the book I consistently find
irritating. I have to guess what kind of thing a class is (Date is one
section, Time in another...), then find that chapter, then I can use the
alphabet... I can see why you wanted to do this, but for me at least, it
didn't work.

What would make me happy, is if you removed the entire library section
(especially things like, in your example sl.pdf, you document base64.rb,
but thats a fairly useless set of two single line wrappers around
pack/unpack that should never have been in the global namespace, why
spend a whole page on it?).

In its place, if you put a chapter on racc, on rexml, on webrick, on
soap4r, etc., tutorial style stuff on how to do useful things, that's
the kind of thing that I don't know will get done in the std lib
documentation, and I would be happy to buy and be able to read on my
couch, whereas it looks like the doc team (yeah team!) are doing good
work in getting the per-API docs in better shape.

Things I would like to see better docs for, at higher than API level:

- c extensions
- swig
- the ruby OO model, especially with a little more reference to java and
  C++'s
- advice on usage, when to freeze things, how to build apis, whether to
  check your arguments types, or just use duck-typing and let things
  unfold as they will

I'm a huge fan of printed docs, generally, but at some point, the std
library API becomes so huge that you get injured lifting the book, and
ruby is getting that direction.

That my 2 bits.

Thanks for the great book, v1,
Sam

Wrote Dave Thomas <dave@pragprog.com>, on Tue, Mar 23, 2004 at 02:46:42AM +0900:

···

Folks:

It's looking as if we're moving towards agreement with Addison Wesley
on getting the rights to Programming Ruby back. This means that we'll
be able to produce an updated version, covering Ruby 1.8. No promises:
we still don't have all the signed agreements, but AW is certainly
being very helpful so far.

Now... I have a question. When it came to documenting the library that
comes with Ruby (the stuff in lib/ and ext/), the original PickAxe
trying to document every method in a subset of the 1.6 distribution: we
picked the library classes and modules that looked as if they were
being used.

In Ruby 1.8, the library has grown astonishingly: I count almost 100
library modules and classes in lib/ alone. If we were to document these
in any kind of detail, the book would grow to 2000 pages, and we
wouldn't be done until 2008 :slight_smile:

At the same time, the ruby-doc folks are making significant inroads in
adding documentation the library itself: this is available both through
ri and as HTML (at ruby-doc.org, for example).

So, this is what I'm thinking. Rather than document all the methods in
all the lib/ and ext/ classes and modules, I'd like to have a one-page
summary for each. Each page would contain a synopsis of the function of
the library, along with a small number of samples of use. The idea is
that you can read through this to find libraries that would be useful,
and then consult the RDoc for details. Think of it as a kind of
exhaustive library cookbook. I've posted sample pages at

   http://www.pragmaticprogrammer.com/extracts/sl.pdf

(These are rough, and contain typesetting problems and other errors---I
just wanted to give folks a feel for what I was talking about).

So, here's the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to
the online or local documentation for the details? (Don't worry about
the built-in stuff: I'm keeping the existing format for all of that, so
you'll still have the complete method listing for String, Array, and
friends).

Cheers

Dave

--
Sam Roberts <sroberts@certicom.com>

3

Dave Thomas dave@pragprog.com writes:

So, here’s the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to
the online or local documentation for the details? (Don’t worry about
the built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

The PDF looks great. I like the “cookbook” summary. That, paired with the new
RDocs, will be a great combination.

I’m glad you’re keeping the core classes (String, Array, and friends). The
HTML version of the built-in classes page from version 1 stays on my Bookmarks
Bar and is heavily referenced.

If you decide to release version 2 of the Pickaxe book electronically, it
would be wonderful to be able to provide links between it and the RDoc
documentation. When I’m looking at the new cookbook, I imagine my next stop
would be the RDocs to get the dirty details. I’m not sure how that would be
possible, though. The book couldn’t link to my local copy of the RDocs, of
course: that can live different places on different systems. Perhaps the
electronic version of the book could come with a snapshot of the RDocs.

Jim

···

–
Jim Menard, jimm@io.com, http://www.io.com/~jimm/
“Mind you, deep in the IBM VM operating system source we once found a
comment that said ‘remember to collect laundry on way home’.”
– Alan J. Flavell in comp.lang.perl.misc

4

So, here’s the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to
the online or local documentation for the details? (Don’t worry about
the built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

I really like it. It’s something that the ruby community lacks: a single
place to look for fairly authoratative examples of all this. The stdlib
docs don’t include enough, often (it’s improving!), so … I’m
impressed.

Ari

5

Dave Thomas wrote:

Folks:

It’s looking as if we’re moving towards agreement with Addison Wesley on
getting the rights to Programming Ruby back. This means that we’ll be
able to produce an updated version, covering Ruby 1.8. No promises: we
still don’t have all the signed agreements, but AW is certainly being
very helpful so far.

Now… I have a question. When it came to documenting the library that
comes with Ruby (the stuff in lib/ and ext/), the original PickAxe
trying to document every method in a subset of the 1.6 distribution: we
picked the library classes and modules that looked as if they were being
used.

In Ruby 1.8, the library has grown astonishingly: I count almost 100
library modules and classes in lib/ alone. If we were to document these
in any kind of detail, the book would grow to 2000 pages, and we
wouldn’t be done until 2008 :slight_smile:

At the same time, the ruby-doc folks are making significant inroads in
adding documentation the library itself: this is available both through
ri and as HTML (at ruby-doc.org, for example).

So, this is what I’m thinking. Rather than document all the methods in
all the lib/ and ext/ classes and modules, I’d like to have a one-page
summary for each. Each page would contain a synopsis of the function of
the library, along with a small number of samples of use. The idea is
that you can read through this to find libraries that would be useful,
and then consult the RDoc for details. Think of it as a kind of
exhaustive library cookbook. I’ve posted sample pages at

http://www.pragmaticprogrammer.com/extracts/sl.pdf

(These are rough, and contain typesetting problems and other errors—I
just wanted to give folks a feel for what I was talking about).

So, here’s the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to the
online or local documentation for the details? (Don’t worry about the
built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

Cheers

Dave

I think this is an excellent idea, what the community is particularly
lacking in terms of documentation is examples and usage. API info is
important, particularly if it’s an obscure section, but when I look at a
new library I want to know what it’s capable of, and that’s what
examples show.

Charles Comstock

6

Dave Thomas wrote:

So, here’s the question: is this the way to go?

Yes.

Are folks happy seeing
this kind of synoptic information in the book, and then referring to the
online or local documentation for the details? (Don’t worry about the
built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

Yes. The book can’t cover everything, but people need to know what else
there is to know. The number of online resources is growing, so it’s
fair to refer readers to other, freely available, documents.

If somebody takes an interest in Ruby, they will likely have an
installation, so they’ll have ri and the rdoc and the means to generate
the HTML files, etc. What they won’t have is any idea of all that’s in
there, so the book can serve as a road map for the more arcane features.

James

7

That’s a sensible approach, but I think you should be flexible about
how much detail each library gets.

For instance, ‘date’ is an important class, and a reader of Pickaxe
should come away fairly expert in its usage. ‘soap’, on the other
hand, is much more “optional”.

The differences between ‘date’ and ‘soap’ are:

  • everyone needs ‘date’ from time to time, but only a few need ‘soap’;
  • someone interested in SOAP (in general) should read a book on SOAP
    (even though it’s not about Ruby), whereas for someone interested
    in ‘date’, Pickaxe is all they’ve got.

So basically, not all libraries are equal, and they shouldn’t be
treated as such. The criteria I identified are the best I can think
of, but there may be a better way to decide what gets the one-page
treatment and what gets more detail.

Layout-wise, I’d probably do a one-pager on all libraries in one
chapter, and then have a few themed chapters where some libraries are
explored in more detail.

HTH,
Gavin

···

On Tuesday, March 23, 2004, 4:46:42 AM, Dave wrote:

So, this is what I’m thinking. Rather than document all the methods in
all the lib/ and ext/ classes and modules, I’d like to have a one-page
summary for each. Each page would contain a synopsis of the function of
the library, along with a small number of samples of use. The idea is
that you can read through this to find libraries that would be useful,
and then consult the RDoc for details. Think of it as a kind of
exhaustive library cookbook.

8

Dave Thomas wrote:

Folks:

It’s looking as if we’re moving towards agreement with Addison
Wesley on getting the rights to Programming Ruby back. This means
that we’ll be able to produce an updated version, covering Ruby
1.8. No promises: we still don’t have all the signed agreements,
but AW is certainly being very helpful so far.

Now… I have a question. When it came to documenting the library
that comes with Ruby (the stuff in lib/ and ext/), the original
PickAxe trying to document every method in a subset of the 1.6
distribution: we picked the library classes and modules that looked
as if they were being used.

In Ruby 1.8, the library has grown astonishingly: I count almost
100 library modules and classes in lib/ alone. If we were to
document these in any kind of detail, the book would grow to 2000
pages, and we wouldn’t be done until 2008 :slight_smile: … Cheers

Dave

I am remembering how wonderful the first “Java in a Nutshell” book
was, and what a disappointment the second edition was. Be very
careful here.

I agree that you need to cover the basic classes…but better to cover
the main classes thoroughly (as a reference) and leave pointers to the
others. Don’t overkill.

My thought would be the best approach would be, after the initial
language definitions and discussions, to take a series of common
tasks, and show how to do them. A good addition would be a
cross-index of task and class, but that might be quite difficult, as
people describe the tasks so differently.

Your initial approach of building the jukebox application was an
excellent approach. Perhaps expand that into things like displaying a
graphic image that goes with the music, simple accounting of which
songs are most popular. Playing music out of the computer’s
speakers. Synthesizing the music from a score. Editing the score.
Printing the score. Etc. With lots of pointers to places on the web
where more information can be found.

P.S.: You seem to have settled on FOX as the display kit, so I don’t
know if what I was suggesting is practical. As usual, a discussion of
alternatives, and why you are choosing the direction you are choosing
is helpful.

P.P.S: Is Ruby2 in the offing? I seem to recall publishers as having
slow turn arounds…so perhaps you had better be covering that, though
whether as a “soon to appear” or as the standard version I don’t know.

9

Personally, I never pull out the pickaxe as a reference. I think its
real strength (and you and Andy’s core strength as a unit) is to help
people understand the high level concepts that are important when
learning a dynamic language like Ruby. To me, the biggest bang for the
buck would be for you to stay at that level, and leave API
documentation to the ruby-doc folks (which could, in this open source
community, theoretically be any/all of us).

Excellent (almost) news on the future of Pick Axe!

Chad

···

On Mar 22, 2004, at 12:46 PM, Dave Thomas wrote:

Folks:

In Ruby 1.8, the library has grown astonishingly: I count almost 100
library modules and classes in lib/ alone. If we were to document
these in any kind of detail, the book would grow to 2000 pages, and we
wouldn’t be done until 2008 :slight_smile:

10

“Dave Thomas” dave@pragprog.com schrieb im Newsbeitrag
news:DFB1150A-7C28-11D8-AA8B-000A95676A62@pragprog.com…

So, here’s the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to
the online or local documentation for the details? (Don’t worry about
the built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

I like that approach if proper online documentation is in place. This is
what happens with the cygwin install:

$ ri String
No ri documentation found in:
/usr/share/ri/1.8/system
/usr/share/ri/1.8/site
/home/Robert/.rdoc

Was rdoc run to create documentation?

I don’t say it’s your fault I just feel that there is no single and
consistent documentation standard for ruby. Although there is ruby-doc.org
IMHO there should be a complete online reference shipped with each
installation. Or am I missing something?

And, yes, the chapter-alphabetical organization makes finding things more
difficult than it should be. That can certainly improved on.

Kind regards

robert
11

Having one page summaries of each library seems to be a useful way to
preview, see what is of interest in order to go elsewhere to dig
deeper. I would like to see that approach taken.

Dave Thomas dave@pragprog.com wrote in message news:DFB1150A-7C28-11D8-AA8B-000A95676A62@pragprog.com…

···

Folks:

It’s looking as if we’re moving towards agreement with Addison Wesley
on getting the rights to Programming Ruby back. This means that we’ll
be able to produce an updated version, covering Ruby 1.8. No promises:
we still don’t have all the signed agreements, but AW is certainly
being very helpful so far.

Now… I have a question. When it came to documenting the library that
comes with Ruby (the stuff in lib/ and ext/), the original PickAxe
trying to document every method in a subset of the 1.6 distribution: we
picked the library classes and modules that looked as if they were
being used.

In Ruby 1.8, the library has grown astonishingly: I count almost 100
library modules and classes in lib/ alone. If we were to document these
in any kind of detail, the book would grow to 2000 pages, and we
wouldn’t be done until 2008 :slight_smile:

At the same time, the ruby-doc folks are making significant inroads in
adding documentation the library itself: this is available both through
ri and as HTML (at ruby-doc.org, for example).

So, this is what I’m thinking. Rather than document all the methods in
all the lib/ and ext/ classes and modules, I’d like to have a one-page
summary for each. Each page would contain a synopsis of the function of
the library, along with a small number of samples of use. The idea is
that you can read through this to find libraries that would be useful,
and then consult the RDoc for details. Think of it as a kind of
exhaustive library cookbook. I’ve posted sample pages at

http://www.pragmaticprogrammer.com/extracts/sl.pdf

(These are rough, and contain typesetting problems and other errors—I
just wanted to give folks a feel for what I was talking about).

So, here’s the question: is this the way to go? Are folks happy seeing
this kind of synoptic information in the book, and then referring to
the online or local documentation for the details? (Don’t worry about
the built-in stuff: I’m keeping the existing format for all of that, so
you’ll still have the complete method listing for String, Array, and
friends).

Cheers

Dave

12

My 2 cents (slightly related to libs): what do you think about a new
section on installation structure, explaining rationale, usage, etc of
main directories, how to install, how to shape a library in order to
install it properly and so on?

Cheers,
Giuliano

Dave Thomas wrote:

Folks:

It’s looking as if we’re moving towards agreement with Addison Wesley on
getting the rights to Programming Ruby back. This means that we’ll be
able to produce an updated version, covering Ruby 1.8. No promises: we
still don’t have all the signed agreements, but AW is certainly being
very helpful so far.

Now… I have a question.

[…]

···

–
If you want to send me an email in the address you have to write ‘p’,
then a dot, followed by ‘bossi’ at ‘quinary’, another dot and ‘com’ at last

13

I loved the first Pickaxe, and I agree that with ri available,
Pickaxe II need not try to document everything. There were
two holes in the first Pickaxe that I think should be filled.
The first is that the insane gotchas that occur when you try
to do math without including mathn were not mentioned. Indeed,
I don’t think the mathn library was mentioned. Hopefully these
bugs will be fixed in Ruby by then, but if not, the book should
warn about them.

(BTW, does anybody know why these haven’t been fixed? They’ve
been known for ages, and since they are fixed by requiring mathn,
I don’t understand why mathn isn’t required automatically when
rational, complex, or matrix are.)

The second was that dealing with international character encodings
was mentioned only perfunctorily. A few examples would have been
very helpful for those of us who live in the wider, non-ASCII world.

The great thing about the Pickaxe is it really teaches you how
to think with Ruby. I had never dealt with such a dynamic, OO
language before (the closest approach having been Python), and
this book opened up a new world of programming for me.

Regards, Bret
Bret Jolly (Jou Lii Bair)

14

What would make me happy, is if you removed the entire library section
(especially things like, in your example sl.pdf, you document base64.rb,
but thats a fairly useless set of two single line wrappers around
pack/unpack that should never have been in the global namespace, why
spend a whole page on it?).

In its place, if you put a chapter on racc, on rexml, on webrick, on
soap4r, etc., tutorial style stuff on how to do useful things, that’s
the kind of thing that I don’t know will get done in the std lib
documentation, and I would be happy to buy and be able to read on my
couch, whereas it looks like the doc team (yeah team!) are doing good
work in getting the per-API docs in better shape.

I’m not sure I agree with this. Programming Ruby fits very well as an
introduction (and then reference) to the language itself. I think having
in-depth examples of how to use libraries is a job for another book
(I haven’t snagged a copy yet, but it seems that Hal’s ‘The Ruby Way’
was made for this purpose). Programming Ruby should merely mention what
exists and then point the reader to the place to get more information.

···

–
Zachary P. Landau kapheine@hypa.net
GPG: gpg --recv-key 0x24E5AD99 | http://kapheine.hypa.net/kapheine.asc

15

Hello Charles,

Monday, March 22, 2004, 8:14:30 PM, you wrote:

I think this is an excellent idea, what the community is particularly
lacking in terms of documentation is examples and usage. API info is
important, particularly if it's an obscure section, but when I look at a
new library I want to know what it's capable of, and that's what
examples show.

And immediately followed by shaking your head because you can't find
out what the method returns or how the error handling is done -
okay real programmers don't need error handling as long as your
computer has a reset button.

So both are very very necessary for a successful library.
But it still leaves the problem that the book would be around 2000
pages. Some publishes like to hear this. So maybe moving from AW to
Wrox Press may be a solution :slight_smile:

···

--
Best regards,
Lothar mailto:mailinglists@scriptolutions.com

17

Folks:

In Ruby 1.8, the library has grown astonishingly: I count almost 100
library modules and classes in lib/ alone. If we were to document
these in any kind of detail, the book would grow to 2000 pages, and
we wouldn’t be done until 2008 :slight_smile:

Personally, I never pull out the pickaxe as a reference. I think its
real strength (and you and Andy’s core strength as a unit) is to help
people understand the high level concepts that are important when
learning a dynamic language like Ruby. To me, the biggest bang for
the buck would be for you to stay at that level, and leave API
documentation to the ruby-doc folks (which could, in this open source
community, theoretically be any/all of us).

I guess I’m just the opposite… the number one thing I’ve used my
Pickaxe for is an API reference. I like having a dead tree form I can
thumb through looking for what I want, and the Pickaxe goes everywhere
with me in my backpack. The second most useful part to me has been the
language reference - when learning Ruby it seemed like I found
something new and cool about the syntax in there every other day. I
personally picked up the high level concepts of a dynamic language
mostly elsewhere, both before and after discovering Ruby. Different
strokes for different folks, I guess.

Anyhow, I like the general direction Dave’s pointing out for this
edition, because there’s a lot of good stuff in the standard library
that folks don’t even know about, but it would be overkill to
comprehensively document all of it in the same book. OTOH, I’d love it
if some of the most useful, general purpose libraries had good,
comprehensive API documentation in the style of the original Pickaxe.
Things like WEBrick, Test::Unit, DRb, optparse, etc., that mailing list
traffic show are being used on a regular basis.

Oh, and mostly unrelated: I hope this edition uses under_score notation
instead of camelCase. I know I was led astray by the Pickaxe in my
early days of Ruby programming :-/

Excellent (almost) news on the future of Pick Axe!

My current one is looking really abused… it’s about time to get a new
one to beat up in my backpack :slight_smile:

Nathaniel
Terralien, Inc.

<:((><

···

On Mar 23, 2004, at 05:57, Chad Fowler wrote:

On Mar 22, 2004, at 12:46 PM, Dave Thomas wrote:

18

My thought would be the best approach would be, after the initial
language definitions and discussions, to take a series of common
tasks, and show how to do them. A good addition would be a
cross-index of task and class, but that might be quite difficult, as
people describe the tasks so differently.

I see that as the role of books such as The Ruby Way and the Developers
Guide. The Pickaxe is really intended to be a guide to Ruby, The
Language. We mention other major libraries briefly, but not in the kind
of depth that other go into. Again, it’s a question of space and
pagecount.

P.S.: You seem to have settled on FOX as the display kit, so I don’t
know if what I was suggesting is practical. As usual, a discussion of
alternatives, and why you are choosing the direction you are choosing
is helpful.

I’m not sure where that impression came from: as it stands right now
I’ve actually removed the Tk chapter from the book. The Ruby GUI
picture is frankly something os a mess, and I didn’t want to go there.
I’d welcome advice here.

P.P.S: Is Ruby2 in the offing? I seem to recall publishers as having
slow turn arounds…so perhaps you had better be covering that, though
whether as a “soon to appear” or as the standard version I don’t know.

The publisher we’re using has the fastest turnaround in the industry…
:slight_smile:

Cheers

Dave
The Pragmatic Bookshelf

···

On Mar 23, 2004, at 1:40, Charles Hixson wrote:

19

I like that approach if proper online documentation is in place.
This is
what happens with the cygwin install:

Could you perhaps contact whoever is responsible for that install and
ask them to check out the RDoc stuff: it should be included.

And, yes, the chapter-alphabetical organization makes finding things
more
difficult than it should be. That can certainly improved on.

And it will be :slight_smile:

Cheers

Dave

···

On Mar 24, 2004, at 1:04, Robert Klemme wrote:

20

Robert Klemme wrote:

Was rdoc run to create documentation?

Did you run rdoc?

I don’t say it’s your fault I just feel that there is no single and
consistent documentation standard for ruby. Although there is ruby-doc.org
IMHO there should be a complete online reference shipped with each
installation. Or am I missing something?

You should, at some point, be able to run rdoc on the full source code
and get the same API docs as you would find on ruby-doc.org (modulo
recent updates to the latest CVS)

I believe there have been discussions (on ruby-core?) on whether this
should happen by default as part of the installation process, or if it
should be a deliberately chosen option (something like --with-rdoc or
whatever).

I’d argue for installing docs by default.

James