develooper Front page | perl.perl5.porters | Postings from November 2003

Re: Poor State of the Man Pages

Thread Previous | Thread Next
From:
Shlomi Fish
Date:
November 27, 2003 12:45
Subject:
Re: Poor State of the Man Pages
Message ID:
Pine.LNX.4.56.0311272242010.12180@vipe.technion.ac.il
On Thu, 27 Nov 2003, Yitzchak Scott-Thoennes wrote:

> On Thu, Nov 27, 2003 at 11:35:15AM +0200, Shlomi Fish <shlomif@vipe.stud.technion.ac.il> wrote:
> > Once we're through, we release Perl 5.8.3 with all of the changes applied.
> > (or maybe delay it to Perl 5.10.x due to configuration management issues)
>
> I think you should aim for 5.8.5 (June 2004) at the earliest.  I also
> assume Nicholas will want the changes to go into bleadperl, and then
> be integrated back to maint.
>
> > Are you with me? I volunteer to take the initial effort and get this
> > effort going. One thing that has to be understood is that the man pages
> > should be clear, explanatory, and organized. We cannot leave
> > "transliterate" as such because it's a piece of UNIX jargon and not plain
> > English. (for example).
>
> Transliterate is a bad example.  It's an English word meaning translating
> by character into a different language or alphabet.  The extension to
> Computer Science should be obvious.
>
> In general, avoiding technical terms, including perl-specific ones,
> will make the documentation worse, not better.  What is needed is a
> short definition of each such term, either where a newbie is likely to
> first encounter it or in a perlglossary.pod or both. (I've always
> wondered why the Camel glossary never made it to the pods.)
>

I never said we should avoid the term transliterate or other computer
terms or jargon. I meant that we should follow them with a short, clear
description explaining what they mean for people who are half-laymen.

"Programming Perl" does just that. (except it has much longer
descriptions) I think we should do so with the man pages too. (except they
should have descriptions that are brief but to the point). Unless of
course, we are going to maintain a different reference (for example, by
forking the man pages).

Regards,

	Shlomi Fish


----------------------------------------------------------------------
Shlomi Fish        shlomif@vipe.technion.ac.il
Home Page:         http://t2.technion.ac.il/~shlomif/

An apple a day will keep a doctor away. Two apples a day will keep two
doctors away.

	Falk Fish

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