Front page | perl.perl5.porters |
Postings from November 2003
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