Perl and the culture of libraries

Ruby
1

http://blog.jrock.us/articles/You%20are%20missing%20the%20point%20of%20Perl.pod

Great article on perl and cpan. I was all ready to say “yeah, ruby has
libraries too - maybe not the tens of thousands cpan has, but i can
usually find what i want” until I read this paragraph:

The important thing about Perl is that we have a culture of writing
good libraries. No Perl programmer would write a few lines of code,
post it to a blog, and call it a “library”. Everyone feels obligated
to create a CPAN distribution, with documentation (sometimes a bit on
the minimal side, but not everyone is a writer), a test suite, a
Makefile, etc. I’m not sure why, but this always happens. I think it’s
because there is a strong convention, and tools that make following
the convention easy.

He’s right - there really is nothing in the ruby culture/toolset that
encourages everything shared to be properly shared. Hoe and friends
[http://nubyonrails.com/articles/tutorial-publishing-rubygems-with-hoe]
are a great step forward, but their use doesn’t seem to be widespread
yet. At the very least, an interesting thing to ponder.

Some ideas I had:

  1. rubyforge should encourage an ecosystem of scripts that works with
    it; right now I can’t even find such scripts other than via “gem
    search” (I’ve filed a suggestion with rubyforge about this).
  2. a majority of the projects on rubyforge (mine included, i admit)
    have no documentation. on the other hand, the landing page of a cpan
    project is the documentation. rubyforge’s default landing page seems
    to contain a lot of information that seems more suited to a sidebar.
  3. perhaps rubygems could support commands like “gem readme”, “gem
    changelog”, “gem todo” and “gem examples” to encourage people to fill
    in such documentation where appropriate

martin

2

I’m on board.
Where do we start ?

Re-face RubyForge to apply the changes you suggest? Who’s maintainer
for
RubyForge ?

Peter F.
(847) 687-7646
Email: [email protected]
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: [email protected]
IM AOL: [email protected]

3

On Tue, Aug 5, 2008 at 6:04 AM, Peter F.
[email protected] wrote:

I’m on board.
Where do we start ?

I think a minimally invasive beginning would be a documentation
skeleton generator. Rdoc is wonderful for what it does, but it doesn’t
provide much “convention-over-configuration” support for
non-source-code-based documentation, and if Rails has done anything,
it has proven the value of a good set of conventions.

martin

4

On Tue, Aug 5, 2008 at 6:31 AM, Peter F.
[email protected] wrote:

Sounds like some changes to rubygems and it’s toolset.

Not really. For instance, if I had a small program, doc_init.rb, that
simply spat out a file project-doc.txt that had the following

Project Name:

Authors:

Short Description:

Long Description:

Usage:

Notes:

it would (a) kickstart the documentation process and (b) give other
tools a standard set of headings to look for (c) give authors a
psychological incentive to include those sections in their
documentation (all of which are useful). Once this achieves a critical
mass, we can ask the rubyforge maintainers to consider looking for a
project-doc.txt in projects and make that the landing page. That in
turn will make sure people who submit to rubyforge include such a
file. It just requires a bit of initial buy-in.

martin

5

Sounds like some changes to rubygems and it’s toolset.

Peter F.
(847) 687-7646
Email: [email protected]
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: [email protected]
IM AOL: [email protected]

6

On Tue, Aug 5, 2008 at 7:05 AM, Peter F.
[email protected] wrote:

Isn’t it true, though, that rubygems are the defacto distribution model for
projects in RubyForge ?
If so, then, like packaging a CPAN .tgz that includes the ./t, ./doc, ./lib
and Makefile.pl,
the “default” gem hierarchy created/expected by the gem tools should also
have ./test, ./doc, and ./lib directories

Yeah, but expecting it is a pretty disruptive change. it’s hard to
do it incrementally. having hoe create a structure like that wouldn’t
be a bad idea, though.

Also, I seem to recall that although many (most?) projects on CPAN include
the usual-suspect titles in the documentation
(Name, Synopsis, Description…), those titles really are purely cultural,
there is nothing in POD spec that declares what the
title should be… just “convention”

However, since Perl has settled on said usual-suspect titles, we might
as well take advantage of their experience and adopt them wholesale :slight_smile:
Again, it wouldn’t be something that, say, the gemspec enforces - all
I want to do is provide a tool to make adding those sections the path
of least resistance.

A lot of this has to do with the 25yrs of history w/ Perl vs the 12yrs
history w/ Ruby. 12 years is a long time… but seems to me
a short time in social-cultural development.

Very true. Nothing says we can’t stand on the shoulders of the perl
giants, though :slight_smile:

martin

7

Isn’t it true, though, that rubygems are the defacto distribution model
for
projects in RubyForge ?
If so, then, like packaging a CPAN .tgz that includes the ./t, ./doc,
./lib
and Makefile.pl,
the “default” gem hierarchy created/expected by the gem tools should
also
have ./test, ./doc, and ./lib directories

Also, I seem to recall that although many (most?) projects on CPAN
include
the usual-suspect titles in the documentation
(Name, Synopsis, Description…), those titles really are purely
cultural,
there is nothing in POD spec that declares what the
title should be… just “convention”

A lot of this has to do with the 25yrs of history w/ Perl vs the 12yrs
history w/ Ruby. 12 years is a long time… but seems to me
a short time in social-cultural development.

Your thoughts ?

Peter F.
(847) 687-7646
Email: [email protected]
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: [email protected]
IM AOL: [email protected]

8

I don’t wish to be critical (I really don’t! That’s not just a way of
opening a sentence!) but in my experience there’s very little
documentation in Ruby at all. And I’m not convinced that having a
little form with each gem giving the name of the author and a brief
description of what it does is going to help that much. Authors that
want to include that are already finding ways of including it in the
rdoc, usually in some sort of ‘readme’ entry.

To forestall criticism of my comment:

  1. Yes, I’m aware that there are any number of excellent books to buy,
    but a FOSS language needs good FOSS documentation.

  2. Yes, I’m aware of the pickaxe, obviously. It’s a first-class (pun
    intended) introduction to the language. And the poignant guide. But
    apart from that, where are the websites with tutorials in the
    medium-to-advanced level? Where’s the wiki that takes you through all
    the gotchas and special features of Ruby?* Other languages have them.

  3. Yes, I’m aware of rdoc. But I’m sorry, that’s not really
    documentation. It’s just a way of reading the comments without having
    to wade through the code. For some people, it’s all that is needed.
    But for others it’s just confusing.

  4. Yes, I’m aware I’m feeling very cranky today. Sorry.

I’m really not trying to pick holes in Ruby. I’m just saying that if
you want to document a gem, you need to write a coherent guide
explaining what it does and pointing out the more common options, with
a couple of tutorials. Writing documentation isn’t easy, of course,
and worse, it takes different skills to writing code. But, it’s not
something that can be skipped.

Shadowfirebird.

  • Okay, we know where that last one is: under 10 feet of spam. Still.
9

On Tue, Aug 5, 2008 at 8:56 AM, Martin DeMello [email protected]
wrote:

The important thing about Perl is that we have a culture of writing
good libraries. No Perl programmer would write a few lines of code,
post it to a blog, and call it a “library”. Everyone feels obligated
to create a CPAN distribution, with documentation (sometimes a bit on
the minimal side, but not everyone is a writer), a test suite, a
Makefile, etc. I’m not sure why, but this always happens. I think it’s
because there is a strong convention, and tools that make following
the convention easy.

I’ve always liked the Perl documentation conventions. Particularly
the fact that every CPAN manpage starts with a Synopsis which
demonstrates the essential usage of the library in a few lines of
code.

–
Avdi

Home: http://avdi.org
Developer Blog: Avdi Grimm, Code Cleric
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com

10

On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird
[email protected] wrote:

I don’t wish to be critical (I really don’t! That’s not just a way of
opening a sentence!) but in my experience there’s very little
documentation in Ruby at all. And I’m not convinced that having a
little form with each gem giving the name of the author and a brief
description of what it does is going to help that much. Authors that
want to include that are already finding ways of including it in the
rdoc, usually in some sort of ‘readme’ entry.

[…]

  1. Yes, I’m aware of rdoc. But I’m sorry, that’s not really
    documentation. It’s just a way of reading the comments without having
    to wade through the code. For some people, it’s all that is needed.
    But for others it’s just confusing.

You can’t have it both ways :slight_smile: And this is indeed the specific problem
I would like to address - rdoc is too tied into the code, and a readme
file isn’t structured enough to get past the blank canvas effect -
it’s a mental effort to decide what to put into it.

martin

11

_Why does a good job of this sort of thing, when he nails the syntax
of, say Hpricot or sqlite in a couple of pages. Really I think that
is the sort of thing that we should be aiming towards.

http://whytheluckystiff.net/articles/aQuickGuideToSQLite.html

12

OTOH, _why is a performance artist, poet, and genius.
A very high bar for us nerdy anti-social shmoes who usually have trouble
coming up with something more creative than “Happy Birthday”.

Peter F.
(847) 687-7646
Email: [email protected]
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: [email protected]
IM AOL: [email protected]

13

On Tue, Aug 5, 2008 at 11:38 AM, Peter F.
[email protected] wrote:

OTOH, _why is a performance artist, poet, and genius.
A very high bar for us nerdy anti-social shmoes who usually have trouble
coming up with something more creative than “Happy Birthday”.

Nevertheless, that article is utterly devoid of typical _why-isms, it
just demonstrates good technical writing. This is a skill all
programmers should have, and it is worth brushing up on as needed. It
sort of goes with the territory, most software is only as good as its
documentation to all but the most inner circles of the technorati.

-greg

14

I’m not quite understanding this relationship thing between models and
tables. What I am trying to do within my view is get the price
information
by referring to it like this:

<%= @item.itemprice.Qty1 %>

In each of my individual views for the item_master table and the
itemprice
table I can get the info directly, but I can’t figure out how to access
the
price that corresponds to the item.

Here is my item.rhtml view test page:

Note: this works

<%= @item.itemDescription %>

This does not

<%= @item.itemprice.Qty1 %>

Below is all my Information:

My Models:

item_master.rb

class ItemMaster < ActiveRecord::Base
has_many :itemprices
has_many :item_sub_prices
has_many :item_price_specials
end

itemprice.rb

class itemprice < ActiveRecord::Base
belongs_to :item_master
end

My Controllers:

item_master_controller.rb

class ItemMasterController < ApplicationController

def show_all
@items = ItemMaster.find(:all)
end

def item
@item = ItemMaster.find(params[:id])
end
end

itemprice_controller.rb

class ItemPriceController < ApplicationController
def show
@price = itemprice.find(params[:id])
end
end

Thanks,

Brian

15

Another thread asks:

Where’s the wiki that takes you through all
the gotchas and special features of Ruby?
Several years ago, the answer would have been RubyGarden – perhaps it
could be again.

To get some discussion started, would someone in the know describe its
current status and prospects?

Are there plans or projects for returning it to a useful resource?

Who are its maintainers and where is it hosted?

What kind of support or assistance would be needed to resolve its
problems?

Are there any special issues that make it especially hard to protect the
Ruby Garden wiki from spam?

What sort of assistance is needed?

– Bill Rutiser

16

What he said.

Or, to reduce it to a simple list:

  • say what the thing does.
  • say why it’s such a cool idea to use it.
  • walk slowly through one or two examples that demonstrate basic use,
    and that use the basic objects and methods.
  • Aim to have the whole thing stretch to 2-4 screens of text.
17

On Aug 5, 2008, at 8:54 AM, Martin DeMello wrote:

You can’t have it both ways :slight_smile: And this is indeed the specific problem
I would like to address - rdoc is too tied into the code, and a readme
file isn’t structured enough to get past the blank canvas effect -
it’s a mental effort to decide what to put into it.

martin

i agreed. pod is good enough without being complicated.

has everyone forgotten about rdtool? we have pod for ruby now.

a @ http://codeforpeople.com/

18

On Aug 5, 2008, at 8:46 AM, Avdi G. wrote:

I’ve always liked the Perl documentation conventions. Particularly
the fact that every CPAN manpage starts with a Synopsis which
demonstrates the essential usage of the library in a few lines of
code.

i have to agree with this. one of the main goals of my main.rb lib
was to be able to enable every program to have a ‘–help’ option,
and to allow writing programs that look like this

Main {

description "

  stuff about the great program

"

def run
do_stuff
end

}

because a script that does not declare what it does in the first 10
lines is evil and a script that does not have ‘–help’ doubly so.

a @ http://codeforpeople.com/

19

On Aug 5, 2008, at 9:46 AM, Gregory B. wrote:

Nevertheless, that article is utterly devoid of typical _why-isms, it
just demonstrates good technical writing. This is a skill all
programmers should have, and it is worth brushing up on as needed. It
sort of goes with the territory, most software is only as good as its
documentation to all but the most inner circles of the technorati.

i humbly disagree with this. unpack ruby 1.6.8 and look at the docs.
matz isn’t a great writer - at least he doesn’t spend his time doing
great writing. i don’t think it detracts one bit from the ruby
language. it’s ok to be good at one thing and let others be good at
other things - it’s the beauty if open source to a certain degree that
we can all row together to get the project done, docs included.

on the other extreme from ruby are ‘ls’ and ‘grep’ - most people have
never read the docs for them and yet manage to use them effectively
each day.

software can be good for a variety of reasons: because it’s simple
(google) or because it’s complex but interesting thereby building an
ecosystem to support itself (rails, facebook). in fact, i’d say that,
to an overwhelmingly large degree, that the most used software in the
world effectively has no documentation, or at least none that anyone
reads… consider email programs, spreadsheet programs, ls, grep,
firefox, and ms-paint… it’s fair to say that 99% of the most
popular software is used without requiring any documentation.

i don’t think we disagree on this point - rather i think that it’s
important to distinguish between ‘libraries’ and ‘applications’
without lumping both into the category of ‘software’. in other words
to recognize that documentation needs are different for different
projects. this is part of what makes a one-shoe-fits-all approach
hard i think. it’s also why the documentation needs of a rails plugin
are quite different for a developer installing the the plugin vs a
graphic designer doing the same. it’s unrealistic to expect the
plugin developer to cater to both.

ps. also worth noting (not to you greg), but for posterity, is that
this thread will consume more energy and words than contributing
documentation to one or two medium sized ruby projects currently just
sitting there in svn or git in all there undocumented glory

pss. http://drawohara.com/post/44678286/eric-hodel-kicks-ass

a @ http://codeforpeople.com/

20

On Aug 5, 2008, at 11:57 AM, ara.t.howard wrote:

i have to agree with this. one of the main goals of my main.rb lib
was to be able to enable every program to have a ‘–help’ option,
and to allow writing programs that look like this

RDoc:Usage extracts the comment at the top of your main program as
your help message (after stripping the ‘#’ characters).

I’m not sure if it is still working, given the changes to RDoc, but as
a concept I still think it’s a nice way to do it: you can read the
source, or do --help, and get the same information, and all without
any extra stuff in your source file.

Dave