perl.documentation

perl.documentation http://www.nntp.perl.org/group/perl.documentation/ ... Copyright 1998-2013 perl.org Thu, 23 May 2013 09:27:31 +0000 ask@perl.org Re: Please, update docs (& pods) for Perl 5.16.3!!! by Leo Lapworth perlfaq was only updated yesterday which I believe was AFTER 5.16.3 was built for testing. It has since been updated into the git repo: http://perl5.git.perl.org/perl.git/commit/f78966ffb0f47ffdd7e0bb07b422308709bd39ae Please join #p5p if this is the sort of thing you are able to help with. Thanks Leo On 7 March 2013 20:26, Joaquin Ferrero <explorer@joaquinferrero.com> wrote: > > And cherry-pick them!!! > > > perlfaq is not updated, in Perl 5.16.3-RC1. > > http://www.nntp.perl.org/group/perl.documentation/2013/03/msg1059.html Thu, 07 Mar 2013 21:00:27 +0000 Please, update docs (& pods) for Perl 5.16.3!!! by Joaquin Ferrero And cherry-pick them!!! perlfaq is not updated, in Perl 5.16.3-RC1. http://www.nntp.perl.org/group/perl.documentation/2013/03/msg1058.html Thu, 07 Mar 2013 20:26:38 +0000 [ANNOUNCE] POD2::ES v5.16.2.02 by Joaquin Ferrero A new release of POD2::ES ------------------------------------------------------------------- Last Changes: 5.16.2.02 January 1, 2013 * Added the translation of perlre.pod and perlgit.pod * Fixed typo in ES.pm * Updated copyright year in ES.pm ------------------------------------------------------------------- Stats: 169 total docs, 109 core docs 80 translated (47.34%) 38 reviewed & published 947,607 total words 34.14% translated (63.61% core docs) 21.35% reviewed & published ------------------------------------------------------------------- Links: Live Stats, Graphs & Tasks: https://docs.google.com/spreadsheet/ccc?key=0AkmrG_9Q4x15dC1MNWloU0lyUjhGa2NrdTVTOG5WZVE Github : https://github.com/zipf/perldoc-es CPAN : http://search.cpan.org/dist/POD2-ES/ metaCPAN : https://metacpan.org/release/POD2-ES -- JF^D http://www.nntp.perl.org/group/perl.documentation/2013/01/msg1057.html Mon, 07 Jan 2013 22:59:45 +0000 [ANNOUNCE] POD2::ES v5.16.2.01 by Joaquín Ferrero Other new release of POD2::ES ------------------------------------------------------------------- Last Changes: 5.16.2.01 November 15, 2012 * Updated to v5.16.2 * Added the translation of perlglossary.pod and perlcheat.pod * Changed the translation of 'closure' * Fixed inconsistent translations of 'built-in' 5.16.1.03 September 9, 2012 * Fixed bug in ES.pm (removed use 5.010 and forgot to change defined-or operator) ------------------------------------------------------------------- Stats: 169 total docs, 107 core docs 78 translated (46.15%) 36 reviewed & published 947,607 total words 33.60% translated (63.33% core docs) 20.56% reviewed & published ------------------------------------------------------------------- Links: Live Stats, Graphs & Tasks: https://docs.google.com/spreadsheet/ccc?key=0AkmrG_9Q4x15dC1MNWloU0lyUjhGa2NrdTVTOG5WZVE Github : https://github.com/zipf/perldoc-es CPAN : http://search.cpan.org/dist/POD2-ES/ metaCPAN : https://metacpan.org/release/POD2-ES -- JF^D http://www.nntp.perl.org/group/perl.documentation/2012/11/msg1056.html Thu, 15 Nov 2012 17:20:42 +0000 [ANNOUNCE] POD2::ES v5.16.1.02 by Joaquín Ferrero Other new release of POD2::ES. ------------------------------------------------------------------- Last Changes: 5.16.1.02 September 7, 2012 * Fixed POD formatting issues in perlhacktut.pod and perlnumber.pod 5.16.1.01 September 6, 2012 * Updated to 5.16.1 * Changed the encoding of all ES docs to UTF-8 * Implemented code and doc changes in ES.pm * Added the translation of perlmod.pod, perlmodinstall.pod, perlclib.pod, and perlhacktut.pod ------------------------------------------------------------------- Stats: 168 docs 76 translated (45.51%) 34 reviewed & published 945,786 total words 31.21% translated (46.46% core docs) 11.60% reviewed & published ------------------------------------------------------------------- Links: Live Stats, Graphs & Tasks: https://docs.google.com/spreadsheet/ccc?key=0AkmrG_9Q4x15dC1MNWloU0lyUjhGa2NrdTVTOG5WZVE CPAN : http://search.cpan.org/dist/POD2-ES/ metaCPAN : https://metacpan.org/release/POD2-ES Github : https://github.com/zipf/perldoc-es Grant Report #3: http://news.perlfoundation.org/2012/09/spanish-localization-of-the-pe-2.html -- JF^D http://www.nntp.perl.org/group/perl.documentation/2012/09/msg1055.html Sat, 08 Sep 2012 08:17:49 +0000 Re: perl 5.16.1 is now available by Joaquín Ferrero El 09/08/12 00:33, Ricardo Signes escribió: > > Don't you know? You never split the party > Clerics in the back to keep those fighters hale and hearty > The wizard in the middle, where he can shed some light > And you never let that damn thief out of sight… > > -- Emerald Rose, Never Split The Party > > We are pleased to announce Perl 5.16.1, the second stable release of > Perl 5.16. > Er... ¿ What is the reason to not include the documentation patched ? perlrun, perlfaq7, perlcheat, perlocale, perlre, perl5140delta, perlbook, perlcall, perlclib, perldata, perldebguts, perldiag, perldsc, perlebcdic, perlexperiment, perlform, perlfunc... and many others... JF http://www.nntp.perl.org/group/perl.documentation/2012/08/msg1054.html Wed, 08 Aug 2012 17:58:29 +0000 PerlDoc-ES project, 43,51% done by Joaquin Ferrero Hello, Status of the project PerlDoc-ES: 66 archives translated (all v5.16) 21 files in process https://github.com/zipf/perldoc-es/tree/master/pod/translated Latest POD2::ES: v5.16.0.04 http://search.cpan.org/perldoc?POD2%3A%3AES The project is at 43.51% done (44.74% of core documentation) 45,436 segments remain :) https://docs.google.com/spreadsheet/ccc?key=0AkmrG_9Q4x15dC1MNWloU0lyUjhGa2NrdTVTOG5WZVE Regards, Joaquín F. http://www.nntp.perl.org/group/perl.documentation/2012/07/msg1053.html Mon, 02 Jul 2012 17:18:28 +0000 Re: documentation for the split command; webpage issues by Smylers An&scaron;a Vernerová writes: > Hello, I would like to report that the current documentation for the > split command is erronerrous. > http://perldoc.perl.org/functions/split.html says: Hi there. Thanks for spotting this, and taking the time to look into how you can report it. > This must come from some edit of the older version of the > documentation, which can be found e.g. at > http://www.tu-chemnitz.de/docs/perldoc-html/functions/split.html : As it happens you can also get to older versions on the perldoc.perl.org site -- see the 'Perl version' box near the top left, which lets you get to pages like this: http://perldoc.perl.org/5.12.2/functions/split.html However, an easier way to check precisely where this came from is to look at the source repository, which is here: http://perl5.git.perl.org/perl.git Click on 'tree' to browse the files, guess that documentation is in the 'pod' subdirectory, see 'perlfunc.pod' in the list, and click 'blame', which takes you to this page: http://perl5.git.perl.org/perl.git/blame/HEAD:/pod/perlfunc.pod Searching that for '$remainder' takes you to the line in question, then clicking the commit ID at the start of that line goes to this commit: http://perl5.git.perl.org/perl.git/commit/bd4675851936488a7b28a813c5b60248be3e733b?f=pod/perlfunc.pod You can then click 'diff' to see exactly what was changed. > When I wanted to report this, I found it hard to find out where and > how I should report. There is a contacts section at the bottom of the > page, Those are contact details for the perldoc.perl.org site, which takes the documentation that comes with Perl, formats it nicely, and makes it available as a handy website. But JJ doesn't change the content, so that needs to be reported upstream. > reporting to the perl 5 porters list did not seem adequate. The perlfunc documentation comes with perl, so the Perl 5 Porters are indeed the people to report this to, preferably using the perlbug command so that it gets tracked in their queue until resolved. If you have a suggested correction you can submit a patch with your bug report. (This would also get you in the credits of the next version of Perl.) See perlhack for friendly instructions on how to do that: http://perldoc.perl.org/perlhack.html Cheers Smylers -- http://twitter.com/Smylers2 http://www.nntp.perl.org/group/perl.documentation/2012/06/msg1052.html Tue, 19 Jun 2012 05:57:11 +0000 Re: documentation for the split command; webpage issues by Leo Lapworth Hi, On 19 June 2012 12:20, Shlomi Fish <shlomif@shlomifish.org> wrote: > On Tue, 19 Jun 2012 09:58:17 +0200 > An&scaron;a Vernerová <ansa211@gmail.com> wrote: > > I would like to report that the current documentation for the split > command > > is erronerrous. > > http://perldoc.perl.org/functions/split.html says: > > > > You can use the perlbug utility for that: > http://perldoc.perl.org/perlbug.html perlbug would work... {snip} > This points to: > > * https://github.com/jonallen/perldoc.perl.org That's for changes to the perldoc.perl.org website - not the Perl documentations. If it's a bug with the actual documentation you need to contact p5p who maintain it (this is mentioned at the bottom of every page on the http://perldoc.perl.org/ site.) P5P mailing list is at: http://lists.perl.org/list/perl5-porters.html I'll let them know. Thanks for reporting it. Leo http://www.nntp.perl.org/group/perl.documentation/2012/06/msg1051.html Tue, 19 Jun 2012 05:51:06 +0000 Re: documentation for the split command; webpage issues by Shlomi Fish Hi An&scaron;a, On Tue, 19 Jun 2012 09:58:17 +0200 An&scaron;a Vernerová <ansa211@gmail.com> wrote: > Hello, > > I would like to report that the current documentation for the split command > is erronerrous. > http://perldoc.perl.org/functions/split.html says: > You can use the perlbug utility for that: http://perldoc.perl.org/perlbug.html > -- > > When I wanted to report this, I found it hard to find out where and how I > should report. There is a contacts section at the bottom of the page, but > neither Joe Allen's link nor the link to the project page seem to work - > and reporting to the perl 5 porters list did not seem adequate. So I hope > this is the right list to report such issues. > Jon Allen's site appears to be down now (don't know why) but I was able to access a snapshot on the Wayback Machine: http://web.archive.org/web/20110724151052/http://perl.jonallen.info/projects/perldoc This points to: * https://github.com/jonallen/perldoc.perl.org which is part of https://github.com/jonallen and there's an E-mail there. I agree that Jon should restore his site to be online. Regards, Shlomi Fish > An&scaron;a -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ UNIX Fortune Cookies - http://www.shlomifish.org/humour/fortunes/ Chuck Norris read the entire English Wikipedia in 24 hours. Twice. Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2012/06/msg1050.html Tue, 19 Jun 2012 04:20:54 +0000 documentation for the split command; webpage issues by Anša Vernerová Hello, I would like to report that the current documentation for the split command is erronerrous. http://perldoc.perl.org/functions/split.html says: -- In time-critical applications, it is worthwhile to avoid splitting into more fields than necessary. Thus, when assigning to a list, if LIMIT is omitted (or zero), then LIMIT is treated as though it were one larger than the number of variables in the list; for the following, LIMIT is implicitly 4: 1. ($login, $passwd, $remainder) = split <http://perldoc.perl.org/functions/split.html>(/:/); -- Calling the third argument $remainer is simply wrong - the remainder is the fourth argument, which is not assigned to anything. This must come from some edit of the older version of the documentation, which can be found e.g. at http://www.tu-chemnitz.de/docs/perldoc-html/functions/split.html : -- The LIMIT parameter can be used to split a line partially ($login, $passwd, $remainder) = split <http://www.tu-chemnitz.de/docs/perldoc-html/functions/split.html>(/:/, $_, 3); When assigning to a list, if LIMIT is omitted, or zero, Perl supplies a LIMIT one larger than the number of variables in the list, to avoid unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need. -- When I wanted to report this, I found it hard to find out where and how I should report. There is a contacts section at the bottom of the page, but neither Joe Allen's link nor the link to the project page seem to work - and reporting to the perl 5 porters list did not seem adequate. So I hope this is the right list to report such issues. An&scaron;a http://www.nntp.perl.org/group/perl.documentation/2012/06/msg1049.html Tue, 19 Jun 2012 00:58:26 +0000 Re: Github changed pod rendering HTML format by Joaquin Ferrero El 25/03/12 12:04, Leon Timmermans escribió: > On Sun, Mar 25, 2012 at 3:10 AM, Joaquin Ferrero > <explorer@joaquinferrero.com> wrote: >> Hi!. >> >> Today, I saw that Github render iso-8859-1 encoded pod pages with a double >> utf8 encoding bug. >> >> Example: >> >> https://github.com/zipf/perldoc-es/blob/master/pod/reviewed/perl.pod >> >> but, one pod utf8 encoded *with* =encoding utf8 tag, renders it well: >> >> >> https://github.com/zipf/perldoc-es/blob/master/pod/translated/perl5101delta.pod#___top >> >> >> ¿Will we need to change all POD documentation to utf8, definitely? >> > > This sounds like a bug in github to me, POD is latin-1 when no > character set is given. As much as I'm in favor of converting to utf8, > github crewing up is not a good reason to do that. > > Leon We are translating POD to Spanish, and this is a mess for our translation software. My vote is for utf8 pod everywhere. JF^D http://www.nntp.perl.org/group/perl.documentation/2012/06/msg1048.html Fri, 15 Jun 2012 02:26:39 +0000 Re: CPAN / new Perl 5 features / Perl upgrade conundrum by Joaquin Ferrero El 31/05/12 16:27, Christian Walde escribió: > On Thu, 31 May 2012 12:34:39 +0200, David Cantrell <david@cantrell.org.uk> wrote: > >> On Wed, May 30, 2012 at 11:00:46AM -0400, Michael Peters wrote: >> >>> Sure, just release a new 1.x version of your module that works for older >>> perls and then a new 2.x version of your module for newer perls and >>> cpXXXan will pick up which ones works for which versions of perl and >>> gives the right one to the right user. >> >> Provided that the PAUSE lets you do that - I don't know if it allows >> version numbers to go backwards. But yes, assuming that it does, then >> that is exactly what would happen. > > Actually, it does not. The pause indexer will reject your upload if it detects version numbers going backwards. > > On the other hand: Releasing a 2.x.y that works on 5.6, then a 2.x.y+1 that works on 5.8, then a 2.x.y+2 that works on 5.16 should do the job fine and the cpanxxx mirrors should pick up the newer versions working on older perls. > This is a problem for POD2::ES, also, because we want to publish POD2::ES v5.14.2.09 and POD2::ES v5.16.0.01 at the same time, mainly for to save the translated OOP pods into v5.14 branch (perlboot, perlbot, perltooc and perltoot are deleted at Perl v5.16) -- JF PerlSpanish Team http://www.nntp.perl.org/group/perl.documentation/2012/05/msg1047.html Thu, 31 May 2012 07:53:06 +0000 Perl v5.16R0, VMS and others docs issues by Joaquín Ferrero Hi! Perl v5.16R0 links README[.](.*) docs from pod/perl$1.pod, but not for perlvms.pod, because perlvms.pod already exist. pod/perlvms.pod and README.vms are different docs. So, README.vms is not installed with the distribution, only perlvms.pod. Another issue (?) is README.micro. It still exists, but is not linked by perl.pod, and therefore perlmicro.pod is not generated. JF^D http://www.nntp.perl.org/group/perl.documentation/2012/05/msg1046.html Mon, 14 May 2012 18:12:06 +0000 [ANNOUNCE] POD2::ES v5.14.2.07. by Joaquin Ferrero Hello, Last Changes of the project PerlDoc-ES: * perlunifaq.pod translated and reviewed * Presented grant proposal to TPF http://news.perlfoundation.org/2012/05/2012q2-grant-proposal-spanish.html The project is at 43.02% done (41.46% of core documentation). Public Progress and Statistics: PerlDoc-ES.Traducción https://docs.google.com/spreadsheet/ccc?key=0AkmrG_9Q4x15dC1MNWloU0lyUjhGa2NrdTVTOG5WZVE For more information on the project, please visit https://github.com/zipf/perldoc-es Regards, Joaquín F. http://www.nntp.perl.org/group/perl.documentation/2012/05/msg1045.html Fri, 04 May 2012 12:12:42 +0000 PerlDoc-ES project, at 33,33% done by Joaquin Ferrero Hello, Last Changes of the project PerlDoc-ES: 49 pod files translated 19 README files translated 31 files in process The project is at 37.45% done (33.33% of core documentation) 55,585 segments remain :) Public Progress and Statistics: PerlDoc-ES.Traducción https://docs.google.com/spreadsheet/ccc?key=0AkmrG_9Q4x15dC1MNWloU0lyUjhGa2NrdTVTOG5WZVE For more information on the project, please visit https://github.com/zipf/perldoc-es Regards, Joaquín F. -- JF^D http://www.nntp.perl.org/group/perl.documentation/2012/04/msg1044.html Fri, 06 Apr 2012 17:49:28 +0000 Re: Github changed pod rendering HTML format by Leon Timmermans On Sun, Mar 25, 2012 at 3:10 AM, Joaquin Ferrero <explorer@joaquinferrero.com> wrote: > Hi!. > > Today, I saw that Github render iso-8859-1 encoded pod pages with a double > utf8 encoding bug. > > Example: > >        https://github.com/zipf/perldoc-es/blob/master/pod/reviewed/perl.pod > > but, one pod utf8 encoded *with* =encoding utf8 tag, renders it well: > > >  https://github.com/zipf/perldoc-es/blob/master/pod/translated/perl5101delta.pod#___top > > > ¿Will we need to change all POD documentation to utf8, definitely? > This sounds like a bug in github to me, POD is latin-1 when no character set is given. As much as I'm in favor of converting to utf8, github crewing up is not a good reason to do that. Leon http://www.nntp.perl.org/group/perl.documentation/2012/03/msg1043.html Sun, 25 Mar 2012 03:04:47 +0000 Github changed pod rendering HTML format by Joaquin Ferrero Hi!. Today, I saw that Github render iso-8859-1 encoded pod pages with a double utf8 encoding bug. Example: https://github.com/zipf/perldoc-es/blob/master/pod/reviewed/perl.pod but, one pod utf8 encoded *with* =encoding utf8 tag, renders it well: https://github.com/zipf/perldoc-es/blob/master/pod/translated/perl5101delta.pod#___top ¿Will we need to change all POD documentation to utf8, definitely? -- JF^D http://www.nntp.perl.org/group/perl.documentation/2012/03/msg1042.html Sat, 24 Mar 2012 18:10:57 +0000 Fw: Two Documents Restored from perl.net.au by Shlomi Fish Begin forwarded message: Date: Sat, 24 Mar 2012 20:00:32 +0200 From: Shlomi Fish <shlomif@shlomifish.org> To: Perl in Israel <perl@perl.org.il> Subject: Two Documents Restored from perl.net.au Hi all. http://perl.net.au/ was a somewhat popular wiki for all things Perl. Then it was heavily spammed, and afterwards went completely offline for many months, and the admins have become busy. Luckily, in the past days I was able to restore some of the contents from the Wayback Machine, and place them here and here: * http://perl-begin.org/FAQs/freenode-perl/ - the Freenode #perl’s FAQ. * http://perl-begin.org/humour/ - a page collecting Perl Humour. I plan to restore more stuff. For how I restored it: I tried several scripts (and a CPAN module) I found online (which were hard to come by, and I was disappointed that apparently the Wayback Machine does not provide a Web API), and eventually used this script written in Python: http://code.activestate.com/recipes/286224-pulling-stuff-out-of-the-internet-archive-wayback-/ I had to modify it to not be recursive. Anyway, enjoy! Regards, Shlomi Fish -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ What Makes Software Apps High Quality - http://shlom.in/sw-quality Every successful open source project will eventually spawn a sub‐project. Please reply to list if it's a mailing list post - http://shlom.in/reply . -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ Chuck Norris/etc. Facts - http://www.shlomifish.org/humour/bits/facts/ Beliefs are what divide people. Doubt unites them. — http://en.wikiquote.org/wiki/Peter_Ustinov Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2012/03/msg1041.html Sat, 24 Mar 2012 11:04:17 +0000 Re: Perl 5 wiki by Gabor Szabo On Mon, Feb 13, 2012 at 5:04 PM, Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 <daxim@cpan.org> wrote: > The [official Perl 5 wiki](http://p3rl.org/wiki) has recently become > unusable for its original purpose, see the > [announcement](http://use.perl.org/~schwern/journal/33751). It is > currently impossible to register as a new user. I sent an email to > <support@socialtext.com> six days ago and have yet to receive an > acknowledgement/reply/fix. I guess you are talking about https://www.socialtext.net/perl5/ While I would like to have a better solution but in the meantime there is the big "Registration and Support" link at the top that leads to a page which tells me to ask one of the administrators to get a new account. Unfortunately I am the only one listed there :-( I don't have any more powers there but I can add new users. Gabor http://www.nntp.perl.org/group/perl.documentation/2012/02/msg1040.html Mon, 13 Feb 2012 08:31:54 +0000 Perl 5 wiki by Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 The [official Perl 5 wiki](http://p3rl.org/wiki) has recently become unusable for its original purpose, see the [announcement](http://use.perl.org/~schwern/journal/33751). It is currently impossible to register as a new user. I sent an email to <support@socialtext.com> six days ago and have yet to receive an acknowledgement/reply/fix. I am looking for a champion to take up the cause: investigate what's going on and keep nagging so that access to registration is restored. In case we cannot get satisfaction in a reasonable time, let's consider cutting ties. Some initial thoughts: * Export everything, tools available from <http://search.cpan.org/~lukec/>. * Evaluate Perl wiki softwares and import. Should support [Wiki Creole](http://enwp.org/Creole_(markup)) and [Markdown](http://enwp.org/Markdown) syntaxes for editing. Usability must pass mst's opinion as "not crap". Must not have URL cruft. Insert your own favourite bikeshed colour here. * Find a reliable host for the software: Perl NOC/digital craftsmen/speedchilli/etc. * Ask [Perl NOC](http://noc.perl.org/) for `wiki.perl.org` CNAME. * Send webmasters of perlfoundation.org and socialtext.net some configuration snippets for their Apache httpd and nginx so that the legacy URLs permanently redirect to the new ones. http://www.nntp.perl.org/group/perl.documentation/2012/02/msg1039.html Mon, 13 Feb 2012 07:05:30 +0000 [ANNOUNCE] POD2::ES v5.14.2.05 by Joaquin Ferrero Hello, A new release of POD2::ES is now available on CPAN. Last Changes: 5.14.2.05 October 30, 2011 * Fixed typo and made other changes in perlpragma.pod 5.14.2.04 October 29, 2011 * Added the translation of perlpragma.pod * Minor changes in perlfaq1.pod and perlutil.pod * Pod fix in perlstyle.pod 5.14.2.03 October 22, 2011 * Added the translation of perlstyle.pod * Minor changes in perldbmfilter.pod 5.14.2.02 October 7, 2011 * Added the translation of perldoc.pod 5.14.2.01 October 6, 2011 * Updated to Perl v5.14.2 * Added the translation of perldbmfilter.pod The project is at 32.28%. For more information on the project, please visit https://github.com/zipf/perldoc-es Best regards, Joaquín http://www.nntp.perl.org/group/perl.documentation/2011/10/msg1038.html Sat, 29 Oct 2011 19:21:50 +0000 Re: About.com Guide for Perl [was Fwd: RE: Guide Application for[Perl]] by Shlomi Fish Hello Joel, sorry for the late response. On Tue, 31 May 2011 11:15:08 -0500 Joel Limardo <joel.limardo@forwardphase.com> wrote: > I was the one who asked for your writing sample. I wanted to see if there > was something fairly obvious in your writing that would cause a rejection. > After looking at the links you provided, I'm sad to say that I agree with > About.com. > Well, in my letter I asked if anyone would be willing to volunteer for maintaining the Perl section of About.com, due to the fact that my application was rejected. The fact that my application was rejected was a given and I assumed there was little or nothing I could do about it. Telling me why my writing is lacking, is besides the point of finding someone to maintain the Perl section on About.com, and I didn't request that input. Thanks for passing your commentary on my writing, but it's not going to help with the issue I raised. Regards, Shlomi Fish -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ Interview with Ben Collins-Sussman - http://shlom.in/sussman Had I not been already insane, I would have long ago driven myself mad. — The Enemy and how I Helped to Fight It Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2011/09/msg1037.html Sat, 10 Sep 2011 03:33:58 +0000 HTTP::Tiny and JSON::PP by Naveed Massjouni I noticed that perldoc.perl.org does not list HTTP::Tiny and JSON::PP as core modules. I believe this is a documentation bug. 5.14 has been out for a while now. I have contacted Jon Allen a couple weeks ago about this and have not heard a response. Hopefully someone on this list can do something about this. Thanks, Naveed http://www.nntp.perl.org/group/perl.documentation/2011/09/msg1036.html Wed, 07 Sep 2011 20:32:46 +0000 Re: new package syntax, where do I return true? by Caleb Cushing On Sat, Jul 2, 2011 at 1:13 AM, Flavio Poletti <flavio@polettix.it> wrote: > i.e. it advices you to return a true value from the *file*, not from the > package. This seems to be confirmed by require's documentation: > >                The file must return true as the last statement to indicate >                successful execution of any initialization code, so it's >                customary to end such a file with "1;" unless you're sure > it'll >                return true otherwise.  But it's better just to put the "1;", >                in case you add more statements. > > Again, we're talking about the file, not any package inside. > > At this point, we could argue that putting the "1;" inside the block makes > the whole code return a true value... but considering that the "1;" is > file-related and that it seems difficult to handle properly in Perl::Critic, > is this worth a crusade? probably not, but I thought that this was the package that needed to be returned true from and not the file. Now I understand. Thanks. -- Caleb Cushing http://xenoterracide.com http://www.nntp.perl.org/group/perl.documentation/2011/07/msg1035.html Sat, 02 Jul 2011 09:17:34 +0000 Re: new package syntax, where do I return true? by brian d foy [[ This message was both posted and mailed: see the "To," "Cc," and "Newsgroups" headers for details. ]] In article <BANLkTikBYCOVX60JyEJNh27ETNYODUXT=w@mail.gmail.com>, Caleb Cushing <xenoterracide@gmail.com> wrote: > Having a little debate over this on a Perl::Critic ticket. I'm not > sure anyone is sure and the docs don't say. > > https://rt.cpan.org/Ticket/Display.html?id=69234 > > > is it package foo { ... 1; } or package foo { ... }; 1; ? or what? > and is it possible this could get clarified in the next edition of the > docs? You don't need to return true from a package. You need to return true from a use-d or require-d file so that the last statement in the file returns true and perl knows it successfully loaded the file. It's nothing to do with packages. You still need that true value even if you have no packages declared in that file. http://www.nntp.perl.org/group/perl.documentation/2011/07/msg1034.html Sat, 02 Jul 2011 07:55:20 +0000 Re: new package syntax, where do I return true? by Chas. Owens On Sat, Jul 2, 2011 at 08:53, Chas. Owens <chas.owens@gmail.com> wrote: > On Sat, Jul 2, 2011 at 00:00, Caleb Cushing <xenoterracide@gmail.com> wrote: >> Having a little debate over this on a Perl::Critic ticket. I'm not >> sure anyone is sure and the docs don't say. >> >> https://rt.cpan.org/Ticket/Display.html?id=69234 snip I have just reread perlmod and perlmodlib. It looks like they both need a decent amount of work to bring them in line with the new package syntax. For instance, Give the module a version/issue/release number. To be fully compatible with the Exporter and MakeMaker modules you should store your module’s version number in a non‐my package variable called $VERSION. This should be a floating point number with at least two digits after the decimal (i.e., hundredths, e.g, "$VERSION = "0.01""). Don’t use a "1.3.2" style version. See Exporter for details. Should probably be changed to refer to the second package argument with a caveat about possibly needing $VERSION to satisfy old static analysis code. -- Chas. Owens wonkden.net The most important skill a programmer can have is the ability to read. http://www.nntp.perl.org/group/perl.documentation/2011/07/msg1033.html Sat, 02 Jul 2011 06:07:07 +0000 Re: new package syntax, where do I return true? by Chas. Owens On Sat, Jul 2, 2011 at 00:00, Caleb Cushing <xenoterracide@gmail.com> wrote: > Having a little debate over this on a Perl::Critic ticket. I'm not > sure anyone is sure and the docs don't say. > > https://rt.cpan.org/Ticket/Display.html?id=69234 > > > is it package foo { ... 1; }  or package foo { ... }; 1; ? or what? > and is it possible this could get clarified in the next edition of the > docs? > -- > Caleb Cushing > > http://xenoterracide.com > My take on this is that package Foo { } is the same thing as { package Foo; } Therefore, if your style allowed { package Foo; 1; } then it should allow package Foo { 1; } However, I think you can make a good argument for not allowing that. A module is not a package. The fact that it is customary for modules to consist of one package sometimes confuses this, but there is no requirement that a module include a package at all. From that basis, I would argue that package Foo { } 1; is more correct. -- Chas. Owens wonkden.net The most important skill a programmer can have is the ability to read. http://www.nntp.perl.org/group/perl.documentation/2011/07/msg1032.html Sat, 02 Jul 2011 05:54:16 +0000 new package syntax, where do I return true? by Caleb Cushing Having a little debate over this on a Perl::Critic ticket. I'm not sure anyone is sure and the docs don't say. https://rt.cpan.org/Ticket/Display.html?id=69234 is it package foo { ... 1; } or package foo { ... }; 1; ? or what? and is it possible this could get clarified in the next edition of the docs? -- Caleb Cushing http://xenoterracide.com http://www.nntp.perl.org/group/perl.documentation/2011/07/msg1031.html Fri, 01 Jul 2011 21:00:16 +0000 Re: About.com Guide for Perl [was Fwd: RE: Guide Application for [Perl]] by Shlomi Fish Hi all, On Tuesday 24 May 2011 22:57:27 Shlomi Fish wrote: > Hi all, > > Can anyone here volunteer to write about Perl for http://perl.about.com/ ? > It's been suffering from a lot of neglect, and my application for a writer > there was rejected (see below). > Someone asked me (in private - :-( ) what my writing sample looked like, and since this was a form submission and it was a long time ago, I don't recall exactly, but I think they were these: * http://www.shlomifish.org/lecture/Perl/Newbies/ * http://perl-begin.org/ Regards, Shlomi Fish > Regards, > > Shlomi Fish > > ---------- Forwarded Message ---------- > > Subject: RE: Guide Application for [Perl] > Date: Tuesday 24 May 2011, 18:01:03 > From: jmola@about.com > To: shlomif@shlomifish.org, shlomif@gmail.com > > > Shlomi, > > While we thank you for taking the time to apply to be an About.com Guide, > we have decided not to accept your application for entry into Prep. A few > common reasons why your application was not accepted include: > > * We are looking for someone with more professional writing experience. > * We are looking for someone with more writing experience in the topic. > * We are looking for someone with different qualifications. > * The writing in the writing sample was not up to our standards or had > typographical errors. > > If you feel that you did not represent yourself to your best advantage in > your application and you wish to apply again, you are more than welcome to > do so at http://beaguide.about.com. In addition, you may also be > interested in applying to be a writer for ConsumerSearch, a member of the > About, Inc. group of companies looking for writers to join their teams. > If so, we encourage you to apply via the following link: > > * Consumer Search: http://www.consumersearch.com/www/jobs.html. > > Thanks again for your application, > > About.com Recruitment and Training Team > > ----------------------------------------- -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ First stop for Perl beginners - http://perl-begin.org/ In Soviet Russia, XSLT codes you. Badly! Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2011/05/msg1030.html Tue, 31 May 2011 04:29:36 +0000 About.com Guide for Perl [was Fwd: RE: Guide Application for [Perl]] by Shlomi Fish Hi all, Can anyone here volunteer to write about Perl for http://perl.about.com/ ? It's been suffering from a lot of neglect, and my application for a writer there was rejected (see below). Regards, Shlomi Fish ---------- Forwarded Message ---------- Subject: RE: Guide Application for [Perl] Date: Tuesday 24 May 2011, 18:01:03 From: jmola@about.com To: shlomif@shlomifish.org, shlomif@gmail.com Shlomi, While we thank you for taking the time to apply to be an About.com Guide, we have decided not to accept your application for entry into Prep. A few common reasons why your application was not accepted include: * We are looking for someone with more professional writing experience. * We are looking for someone with more writing experience in the topic. * We are looking for someone with different qualifications. * The writing in the writing sample was not up to our standards or had typographical errors. If you feel that you did not represent yourself to your best advantage in your application and you wish to apply again, you are more than welcome to do so at http://beaguide.about.com. In addition, you may also be interested in applying to be a writer for ConsumerSearch, a member of the About, Inc. group of companies looking for writers to join their teams. If so, we encourage you to apply via the following link: * Consumer Search: http://www.consumersearch.com/www/jobs.html. Thanks again for your application, About.com Recruitment and Training Team ----------------------------------------- -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ First stop for Perl beginners - http://perl-begin.org/ Knuth is not God! Unless you confuse him with Dijkstra. Please reply to list if it's a mailing list post - http://shlom.in/reply . -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ My Favourite FOSS - http://www.shlomifish.org/open-source/favourite/ Mastering 'cat' is almost as difficult as herding cats. -- http://www.shlomifish.org/humour/bits/Mastering-Cat/ Please reply to list if it's a mailing list post - http://shlom.in/reply . -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ Best Introductory Programming Language - http://shlom.in/intro-lang * Backward compatibility is your worst enemy. * Backward compatibility is your users' best friend. Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2011/05/msg1029.html Tue, 24 May 2011 12:57:48 +0000 Re: insufficient shift operator explanation by Leon Timmermans On Thu, Mar 17, 2011 at 1:36 AM, Chas. Owens <chas.owens@gmail.com> wrote: > Take a look at the explanation at > https://github.com/cowens/perlopquick/raw/master/perlopquick.pod > > I guess I should finish that doc now that I am unemployed. 5.14.0's first release candidate is scheduled for April 1st, code freeze is next Sunday. If it isn't finished quickly, it will have to wait until next year to be included into perl. Leon http://www.nntp.perl.org/group/perl.documentation/2011/03/msg1028.html Thu, 17 Mar 2011 04:02:52 +0000 Re: insufficient shift operator explanation by Chas. Owens On Wed, Mar 16, 2011 at 20:30, herbert breunung <deirdre_skye@web.de> wrote: > on page http://perldoc.perl.org/perlop.html#Shift-Operators > > shift should be explained as the next op below. > if you like i can write a proposal > > cheesrs :) > Take a look at the explanation at https://github.com/cowens/perlopquick/raw/master/perlopquick.pod I guess I should finish that doc now that I am unemployed. -- Chas. Owens wonkden.net The most important skill a programmer can have is the ability to read. http://www.nntp.perl.org/group/perl.documentation/2011/03/msg1027.html Wed, 16 Mar 2011 17:37:12 +0000 insufficient shift operator explanation by herbert breunung on page http://perldoc.perl.org/perlop.html#Shift-Operators shift should be explained as the next op below. if you like i can write a proposal cheesrs :) http://www.nntp.perl.org/group/perl.documentation/2011/03/msg1026.html Wed, 16 Mar 2011 17:31:11 +0000 Re: Current Issues with perlipc.pod - should they be fixed? by Abigail On Mon, Dec 06, 2010 at 08:45:01PM +0200, Shlomi Fish wrote: > On Monday 06 December 2010 19:49:44 Abigail wrote: > > On Mon, Dec 06, 2010 at 07:34:35PM +0200, Shlomi Fish wrote: > > > Now I think that some of my style/best-practices suggestions are an > > > improvement and I'd like to pursue them. > > > > And I'm strongly against that sentiment. > > > > I really do think p5p, and hence the documentation, should *not* have a > > style preference, or have some form of "best practice" (nor do I believe > > you'll find consensus on what "best practice" will be). Style guides, > > coding standards, best practices, or whatever you want to label it only > > gives rise to coding police, and it's only fuel to people who only answer > > questions on usenet or Perlmonks with "well, for starters following these > > as these rules", regardless whether that helps answering the question > > or not. > > Well, I don't frequent either Usenet or Perlmonks, but let me answer. (For the > record, I help a lot on IRC and on mailing lists.) I've collected a longish > list of bad practices to avoid (from PBP and other sources) here: > > http://perl-begin.org/tutorials/bad-elements/ > > Now, I've specifically tried to make it as non-controversial as possible and > avoided recommendations that are a matter of taste, and can be done this way > or another. > > If you think all style guide / best practices / etc. are not helpful, will you > accept code that: > > 1. Lacks all indentation? Unlikely. > > 2. Has magic numbers such as: > > my $n = uc($_[3]); Depends on the usage. I don't have much problems with: $minutes = 60 * $hours; And for manual pages, due to line-length restrictions, I rather accept a numeric literal, than a descriptive name that causes the line to wrap on my terminal. > 3. Has comments or even identifiers in a non-English language? Depends on the environment. > 4. Has duplicate code? Maybe. I do copy-and-paste at $WORK every now and then. Sometimes, the cost of copying is less than the cost of abstracting. It's a trade-off. For documentation, I'm even more willing to accept duplicate code. > 5. Has inconsistent tabs and spaces and looks differently aligned on many tab > widths? Personally, I never use tabs, unless the syntax demands it (like Makefiles). > 6. Has non-descriptive variable names? Reportedly > http://en.wikipedia.org/wiki/Daniel_J._Bernstein uses many single-letter and > double-letter identifiers in his code. Certainly. $i, $n, etc, I use often. For documentation, $foo, $bar, and friends are often acceptable. But avoiding really bad techniques is a far cry from enforcing a certain style. Rejecting code that lacks all indentation isn't the same as changing identation in existing documentation to what someone considers the optimal indentation width. To go back to your suggestions that started this long thread, I don't think any of the proposals fell into your points 1-6. > I know none of these will be acceptible to me, because they are not a matter > of taste, but rather objective measures of the internal quality of the code. > > However, there are a lot of style debates, like which indentation style to > use, or whether to do my ($self, $args) = @_; or my ($self, %args) = @_; or > whether one should avoid using "unless" instead of of "if (!)" altogether > (which I do), or whether one should avoid trailing conditionals (which I also > avoid), etc. etc. These are still a matter of preference and mostly amoral, > and are not covered in my document. > > Now the question is which category making the code strict-safe or using > lexical filehandles belongs to. People have given good arguments for both of > these for many years now, so I think they belong in the things that p5p will > necessitate in code examples (unless someone has a compelling argument why > they are not a good idea). Note that lexical filehandles have been possible since October 1994, with the release of Perl 5.000. It wasn't until the release of 5.6.0 with the introduction of autovivifying that people actually started using them - before then, the extra line of code required apparently didn't offset the benefits. I refuse to believe people wrote bad code for a dozen years (counting pre-perl5 as well). Do we have to document autovivifying file handles? Certainly. Do we have to show how to use lexical filehandles? Yes. Do we have to label code that uses bare file handles as bad, unwanted or outdated? No. As for strictness, let me reiterate my opinion. The majority of the examples of the documentation are code fragments. For brevity reasons, it doesn't state "use strict;" or "use warnings;". Nor does it declare a package, or starts with a she-bang line. Often, it doesn't read any data, nor writes any output. That's all assumed to be "somewhere". Just as declaring used variables with 'my'. After all, if someone wants to copy lines into his program, only he knows where scopes end or begin. Now, if you have some examples where symbolic references are used (and the examples aren't about symbolic references themselves), you're less likely to get opposition from me if you propose a patch to either eliminate the symbolic reference, or a line that points out a symbolic reference is used. But just blindly slapping 'my' everywhere isn't something that gets me cheering. Abigail http://www.nntp.perl.org/group/perl.documentation/2010/12/msg1025.html Mon, 06 Dec 2010 11:24:53 +0000 Re: Current Issues with perlipc.pod - should they be fixed? by Shlomi Fish On Monday 06 December 2010 19:49:44 Abigail wrote: > On Mon, Dec 06, 2010 at 07:34:35PM +0200, Shlomi Fish wrote: > > Now I think that some of my style/best-practices suggestions are an > > improvement and I'd like to pursue them. > > And I'm strongly against that sentiment. > > I really do think p5p, and hence the documentation, should *not* have a > style preference, or have some form of "best practice" (nor do I believe > you'll find consensus on what "best practice" will be). Style guides, > coding standards, best practices, or whatever you want to label it only > gives rise to coding police, and it's only fuel to people who only answer > questions on usenet or Perlmonks with "well, for starters following these > as these rules", regardless whether that helps answering the question > or not. Well, I don't frequent either Usenet or Perlmonks, but let me answer. (For the record, I help a lot on IRC and on mailing lists.) I've collected a longish list of bad practices to avoid (from PBP and other sources) here: http://perl-begin.org/tutorials/bad-elements/ Now, I've specifically tried to make it as non-controversial as possible and avoided recommendations that are a matter of taste, and can be done this way or another. If you think all style guide / best practices / etc. are not helpful, will you accept code that: 1. Lacks all indentation? 2. Has magic numbers such as: my $n = uc($_[3]); ? 3. Has comments or even identifiers in a non-English language? 4. Has duplicate code? 5. Has inconsistent tabs and spaces and looks differently aligned on many tab widths? 6. Has non-descriptive variable names? Reportedly http://en.wikipedia.org/wiki/Daniel_J._Bernstein uses many single-letter and double-letter identifiers in his code. --------------------- I know none of these will be acceptible to me, because they are not a matter of taste, but rather objective measures of the internal quality of the code. However, there are a lot of style debates, like which indentation style to use, or whether to do my ($self, $args) = @_; or my ($self, %args) = @_; or whether one should avoid using "unless" instead of of "if (!)" altogether (which I do), or whether one should avoid trailing conditionals (which I also avoid), etc. etc. These are still a matter of preference and mostly amoral, and are not covered in my document. Now the question is which category making the code strict-safe or using lexical filehandles belongs to. People have given good arguments for both of these for many years now, so I think they belong in the things that p5p will necessitate in code examples (unless someone has a compelling argument why they are not a good idea). Regards, Shlomi Fish > > Pursue all you want. Just expect feedback which may not agree with you. > > > > Abigail -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ Rethinking CPAN - http://shlom.in/rethinking-cpan <rindolf> She's a hot chick. But she smokes. <go|dfish> She can smoke as long as she's smokin'. Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2010/12/msg1024.html Mon, 06 Dec 2010 10:47:03 +0000 Re: Current Issues with perlipc.pod - should they be fixed? by demerphq On 6 December 2010 19:01, Shlomi Fish <shlomif@iglu.org.il> wrote: > Hi Yves, > > On Monday 06 December 2010 10:42:23 demerphq wrote: >> On 5 December 2010 07:54, Naveed Massjouni <naveedm9@gmail.com> wrote: >> > This thread is really depressing.  Personally, I like all of Shlomi's >> > suggestions.  I can't fathom why bareword global filehandles are still >> > pervasive in the perl docs.  But instead of the community getting to >> > discuss the merits of the changes and then have some kind of vote, one >> > maintainer with a big ego can just say, "VETO VETO VETO ... my docs >> > are already perfect!" >> >> I think there is a difference in modifying someone elses >> documentation, and writing a totally new doc. I also think there is a >> big difference between patches to code which fix bugs or add >> functionality, and patches to documentation that is not actually >> wrong, but instead of a style no longer in fashion. To me it is a bit >> like suggesting that Shakespeare needs to be "modernized" because of >> the archaic English he used. >> >> However, if you, or Shlomi think you can write a better perlipc.pod >> from scratch, then you should do so, or any other doc. >> >> If we think it is qualitatively superior then we would probably >> replace the existing version. >> >> More likely we would end up with two docs. And the community would be >> richer for it. >> >> So I think we are right in respecting a given documents artistic >> rights to have their vision presented as they wished, within reason. >> We can always decide not to use the doc at all if we feel they are >> being unreasonable. I doubt you would get a consensus for such an >> extreme action amongst the committers though. I think we generally >> dont feel as strongly about these changes as you seem to. Although I >> respect your reasons for doing so. >> > > Aren't you describing territoriality here? > > * http://en.wikipedia.org/wiki/Territoriality_%28nonverbal_communication%29 > > * http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral- > bazaar/ar01s11.html > > (sorry for the second broken link). I don't know. I'm not even sure that my view is rational or self consistent. I do know that I feel there is some important qualitative difference between modifying code, and modifying a stand alone document like perlipc. > I'm in no position to write my own perlipc.pod from scratch - I'd rather build > on the efforts of tchrist and other contributors. And as Aristotle noted we > don't need another document with the same purpose. And I'd like contributors > to discuss changes to the documentation that they originated based on their > merit and not "veto" them, just because they are territorial about their > documentation. This is also because the documentation affects and reflects on > the collective community of developers and users, and we are all held > responsible for it. Again, I am not sure I agree. I dont feel that *all* of Toms rejections of your changes *are* due to territoriality, although I suspect a few of them might be, and that his general tone suggests he does feel that way. On the other hand I just don't agree with you on some of them. For instance using || instead of or. I prefer the latter, like you I believe, however I actually think in some important respects the other style is better. If you ONLY ever use || and always use parens on function calls then you will never get bitten by weird precedence problems like this: return $foo or $bar; which I see in code more often than I would prefer. Now, like I said, I actually prefer 'or' style, with no parens. But I also know all the places where that can bite you, because I've been bitten. :-) Now you want Tom to change to a style that is objectively inferior in at least one or two ways. You haven't really demonstrated to me that you understand why he prefers his style, or demonstrated to me that you have a cogent argument for using the 'or' form beyond aesthetics. Now on some things I agree. But enough I don't agree with, or think its a dicey argument, that I think Toms opinions should be given extra consideration when we discuss them. >> > What incentive would I or Shlomi or anyone else have to spend their >> > time to try to improve the docs if this is how things work. >> >> We all have different incentives. I would hope that you dont feel that >> a predicate on your contributing is the right to change anything you >> wish however you wish. That is not how it works. No matter how much I >> wish it did sometimes. >> >> I hope you stay positive about contributing to perl, and find other >> subjects where you can do so. We have a lot more to look into than >> Tom's docs. > > The way I see it what happened was that I wrote an email with aspects of > perlipc.pod that I found lacking, and not idiomatic up to recent best > practices, thcrist replying that he doesn't like any of the changes and > VETOing them (without saying why the status quo was better, just by giving > other irrelevant reasons), and some other people discussing why they thought > what I or other people said had a relative merit and should be implemented > (althugh possibly, like Abigail said, not at the utmost priority). I didn't > even start patching perlipc yet (at least not after tchrist's rewrite of its > original version which forced me to restart my work.). > > I also think that the Perl 5 documentation *should* reflect the agreed best > practices (and I don't necessarily mean Damian's PBP). We had lexical > filehandles since at least perl-5.6.x and everyone agrees that they are a best > practice, and "use strict;" is also a good idea, and we encourage everybody to > do "use warnings;" instead of "-w". Therefore, we should practice what we > preach, and make sure that the core docs don't unnecessarily demonstrate > paradigms that have been agreed to be bad for years. Again I think you go a bit too far here. I do agree with the sentiment tho. cheers, Yves -- perl -Mre=debug -e "/just|another|perl|hacker/" http://www.nntp.perl.org/group/perl.documentation/2010/12/msg1023.html Mon, 06 Dec 2010 10:47:00 +0000 Re: Current Issues with perlipc.pod - should they be fixed? by demerphq On 6 December 2010 19:25, Tom Christiansen <tchrist@perl.com> wrote: > This witch-hunt is counter-productive and harmful.  You should not > be offended, or even surprised, if its results are not agreed to. Tom, using terms like "witch-hunt" is not fair - it implies there is malice intent on Shlomi's behalf which I don't think there is any evidence for. Saying stuff like that is at least as harmful to our community as you feel their efforts are, and judging by some of the comments possibly more so. I respect your right to preserve your doc's style. But if you contribute to a public project then you should not be offended, or even surprised, if people argue that it should be patched in ways which are disagreeable to you. cheers, Yves -- perl -Mre=debug -e "/just|another|perl|hacker/" http://www.nntp.perl.org/group/perl.documentation/2010/12/msg1022.html Mon, 06 Dec 2010 10:39:25 +0000 Re: Current Issues with perlipc.pod - should they be fixed? by Tom Christiansen > The way I see it what happened was that I wrote an email with aspects of > perlipc.pod that I found lacking, and not idiomatic up to recent best > practices, thcrist replying that he doesn't like any of the changes and > VETOing them (without saying why the status quo was better, just by giving > other irrelevant reasons), Both of those are falsely stated. First, your notion of irrelevance is mere opinion. Second, I had previously explained my reasoning in full, and so saw no need of pasting the same redundant explanation at each point as some aide-mémoire for those of short attention spans. > I also think that the Perl 5 documentation *should* reflect > the agreed best practices (and I don't necessarily mean > Damian's PBP). You bend that word "agreed" into something it does not mean. When--and only when--you've worked your way down this list far enough that you've finally reached my stuff, do give me a holler. # 1 STRICT 0% success 368 runs = 0 passed + 368 failed < pod/perlapi.pod # 2 Warnings 7% success 368 runs = 24 passed + 344 failed < pod/perlapi.pod # 3 STRICT 33% success 275 runs = 90 passed + 185 failed < pod/perlfunc.pod # 4 STRICT 18% success 200 runs = 37 passed + 163 failed < pod/perlfaq4.pod # 5 Warnings 49% success 275 runs = 136 passed + 139 failed < pod/perlfunc.pod # 6 STRICT 12% success 148 runs = 18 passed + 130 failed < dist/Math-BigInt/lib/Math/BigInt.pm # 7 STRICT 12% success 148 runs = 18 passed + 130 failed < lib/Math/BigInt.pm # 8 Warnings 36% success 200 runs = 72 passed + 128 failed < pod/perlfaq4.pod # 9 STRICT 29% success 150 runs = 44 passed + 106 failed < cpan/CGI/lib/CGI.pm # 10 STRICT 29% success 150 runs = 44 passed + 106 failed < lib/CGI.pm # 11 Warnings 29% success 148 runs = 43 passed + 105 failed < dist/Math-BigInt/lib/Math/BigInt.pm # 12 Warnings 29% success 148 runs = 43 passed + 105 failed < lib/Math/BigInt.pm # 13 STRICT 3% success 98 runs = 3 passed + 95 failed < pod/perlguts.pod # 14 Warnings 4% success 98 runs = 4 passed + 94 failed < pod/perlguts.pod # 15 STRICT 35% success 141 runs = 49 passed + 92 failed < pod/perlretut.pod # 16 Warnings 42% success 150 runs = 63 passed + 87 failed < cpan/CGI/lib/CGI.pm # 17 Warnings 42% success 150 runs = 63 passed + 87 failed < lib/CGI.pm # 18 STRICT 37% success 126 runs = 47 passed + 79 failed < pod/perlop.pod # 19 normal 79% success 368 runs = 290 passed + 78 failed < pod/perlapi.pod # 20 STRICT 4% success 80 runs = 3 passed + 77 failed < pod/perlxs.pod # 21 STRICT 24% success 99 runs = 24 passed + 75 failed < pod/perlfaq5.pod # 22 Warnings 8% success 80 runs = 6 passed + 74 failed < pod/perlxs.pod # 23 STRICT 8% success 78 runs = 6 passed + 72 failed < ext/POSIX/lib/POSIX.pod # 24 STRICT 8% success 78 runs = 6 passed + 72 failed < lib/POSIX.pod # 25 STRICT 5% success 75 runs = 4 passed + 71 failed < cpan/Test-Simple/lib/Test/Builder.pm # 26 STRICT 5% success 75 runs = 4 passed + 71 failed < lib/Test/Builder.pm # 27 STRICT 16% success 83 runs = 13 passed + 70 failed < pod/perltrap.pod # 28 Warnings 11% success 75 runs = 8 passed + 67 failed < cpan/Test-Simple/lib/Test/Builder.pm # 29 Warnings 11% success 75 runs = 8 passed + 67 failed < lib/Test/Builder.pm # 30 Warnings 14% success 78 runs = 11 passed + 67 failed < ext/POSIX/lib/POSIX.pod # 31 Warnings 14% success 78 runs = 11 passed + 67 failed < lib/POSIX.pod # 32 STRICT 0% success 65 runs = 0 passed + 65 failed < cpan/ExtUtils-MakeMaker/lib/ExtUtils/MM_Any.pm # 33 STRICT 0% success 65 runs = 0 passed + 65 failed < lib/ExtUtils/MM_Any.pm # 34 Warnings 2% success 65 runs = 1 passed + 64 failed < cpan/ExtUtils-MakeMaker/lib/ExtUtils/MM_Any.pm # 35 Warnings 2% success 65 runs = 1 passed + 64 failed < lib/ExtUtils/MM_Any.pm # 36 normal 21% success 80 runs = 17 passed + 63 failed < pod/perlxs.pod # 37 STRICT 18% success 76 runs = 14 passed + 62 failed < cpan/Test-Simple/lib/Test/More.pm # 38 STRICT 18% success 76 runs = 14 passed + 62 failed < lib/Test/More.pm # 39 Warnings 51% success 126 runs = 64 passed + 62 failed < pod/perlop.pod # 40 STRICT 21% success 76 runs = 16 passed + 60 failed < pod/perlpacktut.pod # 41 STRICT 15% success 68 runs = 10 passed + 58 failed < pod/perldiag.pod # 42 Warnings 24% success 76 runs = 18 passed + 58 failed < cpan/Test-Simple/lib/Test/More.pm # 43 Warnings 24% success 76 runs = 18 passed + 58 failed < lib/Test/More.pm # 44 STRICT 0% success 56 runs = 0 passed + 56 failed < cpan/Test-Harness/lib/TAP/Parser.pm # 45 STRICT 0% success 56 runs = 0 passed + 56 failed < lib/TAP/Parser.pm # 46 STRICT 17% success 66 runs = 11 passed + 55 failed < pod/perlhack.pod # 47 STRICT 35% success 84 runs = 29 passed + 55 failed < pod/perlsub.pod # 48 Warnings 18% success 66 runs = 12 passed + 54 failed < pod/perlhack.pod # 49 Warnings 46% success 99 runs = 46 passed + 53 failed < pod/perlfaq5.pod # 50 normal 48% success 98 runs = 47 passed + 51 failed < pod/perlguts.pod # 51 Warnings 65% success 141 runs = 92 passed + 49 failed < pod/perlretut.pod # 52 normal 26% success 66 runs = 17 passed + 49 failed < pod/perlhack.pod # 53 Warnings 29% success 68 runs = 20 passed + 48 failed < pod/perldiag.pod # 54 Warnings 43% success 84 runs = 36 passed + 48 failed < pod/perlsub.pod # 55 Warnings 38% success 76 runs = 29 passed + 47 failed < pod/perlpacktut.pod # 56 STRICT 8% success 50 runs = 4 passed + 46 failed < pod/perldata.pod # 57 STRICT 37% success 73 runs = 27 passed + 46 failed < pod/perlfaq8.pod # 58 Warnings 21% success 56 runs = 12 passed + 44 failed < cpan/Test-Harness/lib/TAP/Parser.pm # 59 Warnings 21% success 56 runs = 12 passed + 44 failed < lib/TAP/Parser.pm # 60 Warnings 47% success 83 runs = 39 passed + 44 failed < pod/perltrap.pod # 61 STRICT 7% success 46 runs = 3 passed + 43 failed < cpan/File-Temp/Temp.pm # 62 STRICT 7% success 46 runs = 3 passed + 43 failed < lib/File/Temp.pm # 63 STRICT 22% success 55 runs = 12 passed + 43 failed < pod/perlfaq7.pod # 64 STRICT 32% success 63 runs = 20 passed + 43 failed < pod/perlopentut.pod # 65 STRICT 5% success 44 runs = 2 passed + 42 failed < cpan/Pod-Parser/lib/Pod/Parser.pm # 66 STRICT 5% success 44 runs = 2 passed + 42 failed < lib/Pod/Parser.pm # 67 STRICT 34% success 62 runs = 21 passed + 41 failed < pod/perltoot.pod # 68 Warnings 7% success 44 runs = 3 passed + 41 failed < cpan/Pod-Parser/lib/Pod/Parser.pm # 69 Warnings 7% success 44 runs = 3 passed + 41 failed < lib/Pod/Parser.pm # 70 STRICT 9% success 44 runs = 4 passed + 40 failed < lib/Text/Balanced.pm # 71 STRICT 11% success 45 runs = 5 passed + 40 failed < pod/perlref.pod # 72 STRICT 2% success 40 runs = 1 passed + 39 failed < pod/perlintern.pod # 73 STRICT 9% success 43 runs = 4 passed + 39 failed < cpan/Text-Balanced/lib/Text/Balanced.pm # 74 STRICT 32% success 56 runs = 18 passed + 38 failed < pod/perlcall.pod # 75 Warnings 5% success 40 runs = 2 passed + 38 failed < pod/perlintern.pod # 76 Warnings 14% success 44 runs = 6 passed + 38 failed < lib/Text/Balanced.pm # 77 Warnings 17% success 46 runs = 8 passed + 38 failed < cpan/File-Temp/Temp.pm # 78 Warnings 17% success 46 runs = 8 passed + 38 failed < lib/File/Temp.pm # 79 STRICT 3% success 38 runs = 1 passed + 37 failed < dist/Locale-Maketext/lib/Locale/Maketext.pod # 80 STRICT 3% success 38 runs = 1 passed + 37 failed < lib/Locale/Maketext.pod # 81 STRICT 12% success 42 runs = 5 passed + 37 failed < pod/perliol.pod # 82 Warnings 12% success 42 runs = 5 passed + 37 failed < pod/perliol.pod # 83 Warnings 14% success 43 runs = 6 passed + 37 failed < cpan/Text-Balanced/lib/Text/Balanced.pm # 84 Warnings 26% success 50 runs = 13 passed + 37 failed < pod/perldata.pod # 85 Warnings 49% success 73 runs = 36 passed + 37 failed < pod/perlfaq8.pod # 86 STRICT 27% success 48 runs = 13 passed + 35 failed < pod/perlebcdic.pod # 87 STRICT 41% success 59 runs = 24 passed + 35 failed < pod/perlipc.pod .... # 214 Warnings 64% success 59 runs = 38 passed + 21 failed < pod/perlipc.pod .... #1026 normal 93% success 59 runs = 55 passed + 4 failed < pod/perlipc.pod This witch-hunt is counter-productive and harmful. You should not be offended, or even surprised, if its results are not agreed to. Again I urge you to look first to the beam in your own eye before worrying about the speck in your brother's. Just because it's old advice doesn't make it lose one scintilla of its applicability. --tom http://www.nntp.perl.org/group/perl.documentation/2010/12/msg1021.html Mon, 06 Dec 2010 10:27:00 +0000 Re: Current Issues with perlipc.pod - should they be fixed? by Shlomi Fish Hi Yves, On Monday 06 December 2010 10:42:23 demerphq wrote: > On 5 December 2010 07:54, Naveed Massjouni <naveedm9@gmail.com> wrote: > > This thread is really depressing. Personally, I like all of Shlomi's > > suggestions. I can't fathom why bareword global filehandles are still > > pervasive in the perl docs. But instead of the community getting to > > discuss the merits of the changes and then have some kind of vote, one > > maintainer with a big ego can just say, "VETO VETO VETO ... my docs > > are already perfect!" > > I think there is a difference in modifying someone elses > documentation, and writing a totally new doc. I also think there is a > big difference between patches to code which fix bugs or add > functionality, and patches to documentation that is not actually > wrong, but instead of a style no longer in fashion. To me it is a bit > like suggesting that Shakespeare needs to be "modernized" because of > the archaic English he used. > > However, if you, or Shlomi think you can write a better perlipc.pod > from scratch, then you should do so, or any other doc. > > If we think it is qualitatively superior then we would probably > replace the existing version. > > More likely we would end up with two docs. And the community would be > richer for it. > > So I think we are right in respecting a given documents artistic > rights to have their vision presented as they wished, within reason. > We can always decide not to use the doc at all if we feel they are > being unreasonable. I doubt you would get a consensus for such an > extreme action amongst the committers though. I think we generally > dont feel as strongly about these changes as you seem to. Although I > respect your reasons for doing so. > Aren't you describing territoriality here? * http://en.wikipedia.org/wiki/Territoriality_%28nonverbal_communication%29 * http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral- bazaar/ar01s11.html (sorry for the second broken link). I'm in no position to write my own perlipc.pod from scratch - I'd rather build on the efforts of tchrist and other contributors. And as Aristotle noted we don't need another document with the same purpose. And I'd like contributors to discuss changes to the documentation that they originated based on their merit and not "veto" them, just because they are territorial about their documentation. This is also because the documentation affects and reflects on the collective community of developers and users, and we are all held responsible for it. > > What incentive would I or Shlomi or anyone else have to spend their > > time to try to improve the docs if this is how things work. > > We all have different incentives. I would hope that you dont feel that > a predicate on your contributing is the right to change anything you > wish however you wish. That is not how it works. No matter how much I > wish it did sometimes. > > I hope you stay positive about contributing to perl, and find other > subjects where you can do so. We have a lot more to look into than > Tom's docs. The way I see it what happened was that I wrote an email with aspects of perlipc.pod that I found lacking, and not idiomatic up to recent best practices, thcrist replying that he doesn't like any of the changes and VETOing them (without saying why the status quo was better, just by giving other irrelevant reasons), and some other people discussing why they thought what I or other people said had a relative merit and should be implemented (althugh possibly, like Abigail said, not at the utmost priority). I didn't even start patching perlipc yet (at least not after tchrist's rewrite of its original version which forced me to restart my work.). I also think that the Perl 5 documentation *should* reflect the agreed best practices (and I don't necessarily mean Damian's PBP). We had lexical filehandles since at least perl-5.6.x and everyone agrees that they are a best practice, and "use strict;" is also a good idea, and we encourage everybody to do "use warnings;" instead of "-w". Therefore, we should practice what we preach, and make sure that the core docs don't unnecessarily demonstrate paradigms that have been agreed to be bad for years. Regards, Shlomi Fish -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ My Public Domain Photos - http://www.flickr.com/photos/shlomif/ <rindolf> She's a hot chick. But she smokes. <go|dfish> She can smoke as long as she's smokin'. Please reply to list if it's a mailing list post - http://shlom.in/reply . http://www.nntp.perl.org/group/perl.documentation/2010/12/msg1020.html Mon, 06 Dec 2010 10:03:04 +0000