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

Re: Poor State of the Man Pages

Shlomi Fish
November 27, 2003 12:45
Re: Poor State of the Man Pages
Message ID:
On Thu, 27 Nov 2003, Yitzchak Scott-Thoennes wrote:

> On Thu, Nov 27, 2003 at 11:35:15AM +0200, Shlomi Fish <> 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).


	Shlomi Fish

Shlomi Fish
Home Page:

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

	Falk Fish Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About