Front page | perl.documentation |
Postings from December 2010
Hi Abigail, On Sunday 05 December 2010 18:43:44 Abigail wrote: > On Sun, Dec 05, 2010 at 01:54:29AM -0500, Naveed Massjouni 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!" Is that how things work in the perl community? > > 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. > > People are saying the perlipc docs are Unix centric, which they probably > are. Adding some paragraphs and examples how to do IPC on VMS and Windows > is probably a much better way to improve the documentation than insisting > bare file handles aren't used, or claiming 'or' is somehow better than > '||'. > > There's a lot of the documentation that can be improved; it's badly > organized [*], things are hard to find [*], incorrectly documented [*], > it's missing lots of examples, and it's probably too Unix centric [+]. > I think we have a long way to go before the most constructive thing that > can be done with documentation is twiddling with the coding style of > examples. I agree that there are many aspects where the documentation could use some improvements. However, if I (or someone else) step forward and offer to volunteer my time in changing one of the *.pod files in a certain aspect, then either my suggestion is an improvement or it detracts from the value of the documentation. If my suggestion is indeed an improvement (no matter how small), then I believe that my suggestion for modification should be approved, which will allow me to work on the patch with bigger confidence that it will eventually be applied and thus improve the overall state of the documentation. Or to use the common proverb "One bird in the hand is better than two in the bush." (or "One bird in the hand is better than ten in the tree." as the Arabs say.). Now I think that some of my style/best-practices suggestions are an improvement and I'd like to pursue them. I also think that we should show how to write the sockets' code using IO::Socket and friends rather than using the lower-level API calls, which are no longer recommended (and have not been for years). May I pursue that? Regards, Shlomi Fish -- ----------------------------------------------------------------- Shlomi Fish http://www.shlomifish.org/ First stop for Perl beginners - http://perl-begin.org/ <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 .Thread Previous | Thread Next