Perl and the culture of libraries

ruby-talk
41

i agreed. pod is good enough without being complicated.

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

a @ http://codeforpeople.com/

···

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

--
we can deny everything, except that we have the possibility of being better. simply reflect on that.
h.h. the 14th dalai lama

42

Hi --

···

On Thu, 7 Aug 2008, James Gray wrote:

On Aug 6, 2008, at 9:43 AM, David A. Black wrote:

Also, since something like github can arise and
change the landscape, simply by being there, I believe it's
fundamentally wrong to look at the whole thing as based on consensus.

That's an interesting view and maybe you are right.

I took it more to mean that the current system is less than ideal and all you need to do is produce a significantly better application, which some think github is, to capture some mindshare.

That's really what I mean by "something like github": a system that
some percentage of people like and therefore decide to use.

David

--
Rails training from David A. Black and Ruby Power and Light:
  * Advancing With Rails August 18-21 Edison, NJ
  * Co-taught by D.A. Black and Erik Kastner
See http://www.rubypal.com for details and updates!

43

Tom Copeland wrote:

RubyForge already has an Advogato style rating system for developers,
I can't remember if it's enabled or disabled by default, but it's
optional. I think it *should* be optional, but it does allow people
to rate each other on a few different metrics.

Rating *developers* is far less useful in the grand scheme of things.
Rating *projects* on the other hand lets users solve the "searching
for foo returns 20 hits - which one do I want" problem

GForge doesn't seem to support rating projects AFAIK. Could be done, although folks might value Mercurial support more. I need to do a survey or something.

There was gemtacular.com, but it appears to be dead. Anyone know what happened?

It might be nice to have some sort of rating on the RF page.

Regards,

Dan

···

On Aug 6, 2008, at 9:13 PM, Martin DeMello wrote:

On Wed, Aug 6, 2008 at 6:05 PM, Gregory Brown >> <gregory.t.brown@gmail.com> wrote:

44

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 Fitzgibbons
(847) 687-7646
Email: peter.fitzgibbons@gmail.com
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: pjfitzgibbons@hotmail.com
IM AOL: peter.fitzgibbons@gmail.com

···

On Tue, Aug 5, 2008 at 10:24 AM, Shadowfirebird <shadowfirebird@gmail.com>wrote:

_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

On Tue, Aug 5, 2008 at 3:54 PM, Martin DeMello <martindemello@gmail.com> > wrote:
> On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird <shadowfirebird@gmail.com> > 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.
>
> [...]
>
>> 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.
>
> 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
>
>

--
All you can do is try to know who your friends are as you head off to
the war / Pick a star on the dark horizon and follow the light

45

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

46

I had indeed!! Thanks for the reminder.

martin

···

On Tue, Aug 5, 2008 at 9:59 AM, ara.t.howard <ara.t.howard@gmail.com> wrote:

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.

47

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

···

On Tue, Aug 5, 2008 at 11:38 AM, Peter Fitzgibbons <peter.fitzgibbons@gmail.com> 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".

--
Killer Ruby PDF Generation named after a magnificent sea creature:
GitHub - practicingruby/prawn: THIS REPOSITORY HAS MOVED TO: | Non-tech stuff at:
http://metametta.blogspot.com

48

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.

···

On Tue, Aug 5, 2008 at 4:46 PM, Gregory Brown <gregory.t.brown@gmail.com> wrote:

On Tue, Aug 5, 2008 at 11:38 AM, Peter Fitzgibbons > <peter.fitzgibbons@gmail.com> 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

--
Killer Ruby PDF Generation named after a magnificent sea creature:
GitHub - practicingruby/prawn: THIS REPOSITORY HAS MOVED TO: | Non-tech stuff at:
http://metametta.blogspot.com

--
All you can do is try to know who your friends are as you head off to
the war / Pick a star on the dark horizon and follow the light

49

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/

···

On Aug 5, 2008, at 9:46 AM, Gregory Brown 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.

--
we can deny everything, except that we have the possibility of being better. simply reflect on that.
h.h. the 14th dalai lama

50

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.

Fair enough, I definitely didn't mean to overgeneralize. But I still
stand by the point that programmers *should* have a decent technical
writing skills. You're absolutely right that when software is
interesting enough, people will contribute documentation. However,
the farther away from the author of the software you go, the more
difficult it is for someone to write about the topic. I'm not talking
about tutorials and walk-throughs here, but API documentation. Eric
Hodel kicks ass for a reason, and that's because he's willing to read
code that he didn't write and document it so others don't have to.
This is something we can appreciate, but not something that should be
expected. (Again, I use 'should' in the sense of 'would be best', not
in the sense of 'absolutely must')

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.

This is a good point. I definitely overgeneralized by lumping
everything into 'software'. I'm talking about the things that
actually *do* need documentation, such as complicated libraries or
things at that level of complexity.

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

Or continuing to document Ruby itself, as much of the standard library
still leaves something to be desired for. (Despite the hard work of
those who've made great progress on this over the last couple years)

-greg

···

On Tue, Aug 5, 2008 at 1:07 PM, ara.t.howard <ara.t.howard@gmail.com> wrote:

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

--
Killer Ruby PDF Generation named after a magnificent sea creature:
GitHub - practicingruby/prawn: THIS REPOSITORY HAS MOVED TO: | Non-tech stuff at:
http://metametta.blogspot.com

51

I agree with Advi and Martin that the landing page of a project is
important. The CPAN authors' documentation quality improved because of
CPAN, not the other way around. Rubyforge would lead to better Ruby
libraries if it looked less like Sourceforge and more like the module
pages at http://search.cpan.org. This is not to knock Rubyforge; it
filled a community need. But I think the community deserves more now.

On that note, let's look at a sample distribution page (http://
search.cpan.org/~abw/Template-Toolkit-2.19/). For those unfamiliar
with CPAN, a distribution is sort of the "top level"; it can contain
many modules. CPAN is a lot more than well-documented modules. There
are ratings and reviews, which can help when your searches bring up
multiple modules that do the same thing. I find it useful for
identifying abandon-ware: sometimes you'll see in a review that the
module has been superceded by another. There is also a gaggle of
volunteers who test Perl modules on various platforms. This is
invaluable if you are using a non-mainstream environment (e.g. cygwin)
or if the module has C extensions. And it's fairly automated; there's
a CPAN module called Test::Reporter and a special version of CPAN
(CPANPLUS) that can automatically download a module, run its test
suite, and report results. You can also find dependencies prior
versions. Like Rubyforge, there are discussions and bug reporting that
are sometimes used, sometimes not.

Module authors tend to use Module::Starter which is just like hoe, in
that it generates a nice module skeleton, ready to submit to CPAN.
Another thing I noticed about module authors is that they tend to use
more pragmatic, namespaced module names, i.e. they would tend to use a
name like "PDF::Simple" instead of "prawn". Though this may be due to
the fact that 14,000 modules require a bit more organization and
findability.

If anything could make CPAN better it is more user-generated content.
It would be neat to let users add additional usage examples to the
synopses, perhaps comment on (or even update) the docs (like DocBox,
sorta).

Anyway I think the Ruby community would benefit from taking a page or
two from the CPAN playbook.

-- Mark.

52

There is a (hair brained) reason why I chose the name. It is to keep
Prawn out of the PDF namespace until it is ready to replace the
current defacto standard PDF::Writer library.

Details at:
http://groups.google.com/group/prawn-ruby/msg/f6aee1d625600146

···

On Tue, Aug 5, 2008 at 4:33 PM, Mark Thomas <ruby@thomaszone.com> wrote:

Module authors tend to use Module::Starter which is just like hoe, in
that it generates a nice module skeleton, ready to submit to CPAN.
Another thing I noticed about module authors is that they tend to use
more pragmatic, namespaced module names, i.e. they would tend to use a
name like "PDF::Simple" instead of "prawn". Though this may be due to
the fact that 14,000 modules require a bit more organization and
findability.

53

While there is no hard standard for Ruby, the general convention for
namepaces is the opposite of Perl.

In Perl for instance you might find "PDF::EasyPDF" or "PDF::API2". It
is the second (or last) part of the namespace that makes it unique.
This leads to many project names having more technical names (eg.
API2), rather than colorful names.

In the Ruby world the general convention has moved in the opposite
order. With the unique name coming before the technical
classification. Eg. RedCloth::TextileDoc, or LibXML::XML::Document.

The reason for the difference stems from the fact that Perl
development is organized around CPAN, which is organized by module
namespace, whereas Ruby development is much more decentralized and the
main organizing factor is RubyGems with organizes us by project names.
I also suspect this difference arises in no small part to the fact
that Ruby file names do not have to match our module names (though it
can be a helpful practice to do so).

We can of course argue about which is better. Some Ruby developers
have taken to trying the Perl way, but b/c of the decentralized nature
of Ruby development, name clashes in these cases are not uncommon. I
find the Ruby convention preferable, since it allows for more easily
including modules into my own for convenience. Eg.

  module MyApp
    include LibXML
    doc = XML::Document.new
    ...
  end

T.

···

On Aug 5, 4:33 pm, Mark Thomas <r...@thomaszone.com> wrote:

I agree with Advi and Martin that the landing page of a project is
important. The CPAN authors' documentation quality improved because of
CPAN, not the other way around. Rubyforge would lead to better Ruby
libraries if it looked less like Sourceforge and more like the module
pages athttp://search.cpan.org. This is not to knock Rubyforge; it
filled a community need. But I think the community deserves more now.

On that note, let's look at a sample distribution page (http://
search.cpan.org/~abw/Template-Toolkit-2.19/). For those unfamiliar
with CPAN, a distribution is sort of the "top level"; it can contain
many modules. CPAN is a lot more than well-documented modules. There
are ratings and reviews, which can help when your searches bring up
multiple modules that do the same thing. I find it useful for
identifying abandon-ware: sometimes you'll see in a review that the
module has been superceded by another. There is also a gaggle of
volunteers who test Perl modules on various platforms. This is
invaluable if you are using a non-mainstream environment (e.g. cygwin)
or if the module has C extensions. And it's fairly automated; there's
a CPAN module called Test::Reporter and a special version of CPAN
(CPANPLUS) that can automatically download a module, run its test
suite, and report results. You can also find dependencies prior
versions. Like Rubyforge, there are discussions and bug reporting that
are sometimes used, sometimes not.

Module authors tend to use Module::Starter which is just like hoe, in
that it generates a nice module skeleton, ready to submit to CPAN.
Another thing I noticed about module authors is that they tend to use
more pragmatic, namespaced module names, i.e. they would tend to use a
name like "PDF::Simple" instead of "prawn". Though this may be due to
the fact that 14,000 modules require a bit more organization and
findability.

54

There is a (hair brained) reason why I chose the name. It is to keep
Prawn out of the PDF namespace until it is ready to replace the
current defacto standard PDF::Writer library.

hee hee, I didn't mean to snipe at your name in particular, it's just
the first example that came to mind (I had just looked at your latest
release). Nice work, by the way.

55

Gregory Brown wrote:

···

On Tue, Aug 5, 2008 at 4:33 PM, Mark Thomas <ruby@thomaszone.com> wrote:

Module authors tend to use Module::Starter which is just like hoe, in
that it generates a nice module skeleton, ready to submit to CPAN.
Another thing I noticed about module authors is that they tend to use
more pragmatic, namespaced module names, i.e. they would tend to use a
name like "PDF::Simple" instead of "prawn". Though this may be due to
the fact that 14,000 modules require a bit more organization and
findability.

There is a (hair brained) reason why I chose the name. It is to keep
Prawn out of the PDF namespace until it is ready to replace the
current defacto standard PDF::Writer library.

There's no need to replace.

  Prawn::PDF::Writer

Then a user can

  include Prawn

That's a solid practice.

T.
--
Posted via http://www.ruby-forum.com/\.

56

Is there anything we can do on RubyForge to encourage people with
documentation-writing skills to contribute, and to match them up with
projects that need documentation?

57

No worries, that question came up a few times in the last couple days
and I felt like I needed to retrofit an answer to it that sounded
good. Truly I just like the word. :slight_smile:

···

On Tue, Aug 5, 2008 at 5:18 PM, Mark Thomas <ruby@thomaszone.com> wrote:

There is a (hair brained) reason why I chose the name. It is to keep
Prawn out of the PDF namespace until it is ready to replace the
current defacto standard PDF::Writer library.

hee hee, I didn't mean to snipe at your name in particular, it's just
the first example that came to mind (I had just looked at your latest
release). Nice work, by the way.

--
Killer Ruby PDF Generation named after a magnificent sea creature:
GitHub - practicingruby/prawn: THIS REPOSITORY HAS MOVED TO: | Non-tech stuff at:
http://metametta.blogspot.com

58

Except for the fact that I'm the current maintainer of PDF::Writer and
I don't want to continue to maintain a library that should be retired
as soon as possible.

Creating confusion by layering an additional namespace on things is
not what I call a solid practice :-/

Instead, I'll just wait as long as it takes where people support the jump.

-greg

···

On Wed, Aug 6, 2008 at 9:39 AM, Thomas Sawyer <transfire@gmail.com> wrote:

There's no need to replace.

Prawn::PDF::Writer

Then a user can

include Prawn

That's a solid practice.

--
Technical Blaag at: http://blog.majesticseacreature.com | Non-tech
stuff at: http://metametta.blogspot.com

59

Some sort of coverage report would be neat. This (yet again) gets back
to my idea of having a few standardised documentation sections as a
baseline - there's a quick, automated way to report which projects are
missing which sections. Once that was done, people could scan the
list, find a missing section they felt like contributing, and do so.

A complicating factor is that on CPAN one project corresponds to one
module/program, whereas on rubyforge there are often multiple packages
under the umbrella of a single project.

martin

···

On Fri, Aug 8, 2008 at 1:06 PM, Shadowfirebird <shadowfirebird@gmail.com> wrote:

Is there anything we can do on RubyForge to encourage people with
documentation-writing skills to contribute, and to match them up with
projects that need documentation?