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

Re: Poor State of the Man Pages

From:
Yitzchak Scott-Thoennes
Date:
November 27, 2003 11:52
Subject:
Re: Poor State of the Man Pages
Message ID:
20031127195236.GB420@efn.org
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.)



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