develooper Front page | perl.module-authors | Postings from November 2005

Re: Module abstract: Is its length still limited?

Thread Previous | Thread Next
From:
Sam Vilain
Date:
November 8, 2005 18:11
Subject:
Re: Module abstract: Is its length still limited?
Message ID:
1131502258.13337.29.camel@wilber.wgtn.cat-it.co.nz
On Mon, 2005-11-07 at 21:08 -0500, Ricardo SIGNES wrote:
> * "Andreas J. Koenig" <andreas.koenig.gmwojprw@franz.ak.mind.de> [2005-11-07T17:29:50]
> > I will be very happy if you guys decide something and let me know.
> > I'll adjust the code for the forms on PAUSE then.
> 
> Here's my official vote:
> 
> (length $module_name + length $abstract + 3) should be under 80.
> 
> This means that the whole header and abstract will fit in one line.
> That's more than 44 characters for short module names.  Longer module
> names, which should be pretty descriptive, need shorter abstracts.
> 
> Wombat - a framework for building reusable fruit-counting applications
> Application::Framework::FruitCounting - for reusable produce applications
> 

My feeling is that this wouldn't really work when the module name gets
too long, for example when a namespace under which you are contributing
has chosen verbose terms.

For keeping your source code at 80 characters wide, it should be
perfectly legal to wrap that line in the source; it's not a verbatim
block so all Pod parsers SHOULD see it as a flowed paragraph.  Whether
or not this is true for all relevant parsers is another story.
Personally I'd call it a bug if they don't follow the POD rules, though.

I also feel that the total length of those two is somewhat irrelevant
for its intended use - for instance, if you are browsing modules on
search.cpan.org, the module names and abstracts are both flush left.
Tabular format works better like that.

I think the key question is more along the lines of, how much text do
you want to see while you are reading the abstract for a whole bunch of
modules?  What length is "about right"?

I suggested 60 because it's just a *little* bit longer, to allow for
better word choices here and there, but still too short for rambling.
Perhaps 80 is fine, too.

I had a read through the modules by the authors listed in the other
e-mail, AUTRIJUS, BDFOY, and DCONWAY, and I couldn't really see any
obviously "overly squeezed" abstracts.  Except perhaps QM for "Quantum
Mechanical".

Can anyone find any examples of abstracts that they think are inadequate
due to size restrictions?

Sam.


Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About