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.
[*] If I ever have a couple of spare months, I want to rewrite the
thingserlre documentation.
[+] Probably strongly influenced by the fact the majority of perl and
Perl documentation authors are native Unixians.
Abigail
