Re: [PATCH] perlipc.pod Revamp

Hi Paul,

thanks for your E-mail.

On Monday 01 November 2010 16:47:50 Paul Johnson wrote:
> On Thu, Oct 28, 2010 at 06:18:01PM +0200, Shlomi Fish wrote:
> > This is a new version of the patch for revamping perlipc.pod now that t=
he
> > whitespace normalisation patch was committed.
>=20
> Hello Shlomi,
>=20
> [ Apologies to all for the length of this post.  If you don't want to
> read it all, please skip to section 5 at the bottom. ]
>=20
> I find myself uneasy with the changes you are proposing in this patch.
> I have given the matter a little thought and would like to explain why
> that is so.
>=20
> We have a document describing the way in which contributed modules are
> to be managed within the perl core.  This is perlpolicy.pod.  Please
> take a moment read this document if you are not familiar with it. =20

Read it now.

> The
> relevant section is entitled "CONTRIBUTED MODULES" with the sub-heading
> "A Social Contract about Artistic Control".
>=20
> Although this document does not specifically mention documentation, I
> believe that many of the principles defined therein are applicable to
> documentation as well as code and perhaps even more so to code within
> documentation.

Actually, it does mention documentation under "MAINTENANCE BRANCHES" saying:

{{{      =20
=B7 Documentation updates are acceptable.
}}}

I also disagree that we should treat the core documentation (which exists o=
nly=20
in the core) in the same way that we treat dual-life modules.

>=20
> Writing documentation is hard.  Writing good documentation is even
> harder.  With that in mind, I am grateful to anyone to attempts such a
> task.  However, one of the problems Perl now faces, in my opinion, is
> not a dearth of documentation, but rather an abundance of documents
> which are losing cohesion.  Most aspects of the language are documented,
> if only you can find the correct location.  This is not a simple problem
> to solve, and it gets slightly harder every time someone comes with a
> well intentioned and locally useful documentation patch, adding more
> details or examples to some section which they had found less than
> clear.

OK, do you think my proposed series-of-patches alleviates this problem?

>=20
> However, that is not the problem you are trying to solve.  I believe
> that you are wanting to modernise the code examples to demonstrate best
> practices and (perhaps) to make them into standalone snippets that can
> be copied and pasted into users' code.

Right.

>=20
> Whilst this, on the surface, might be considered a laudable goal, I do
> have a number of concerns, not specifically about the changes you have
> made (although many of them do concern me), but more generally about the
> direction in which this takes us.  Let me try to explain some of my
> concerns.
>=20
> 1.  I'm not convinced that we would be able to get a consensus on what
>     the best practices are that we would like to promote.  For example,
>     I would consider some of the changes you have made to be changes for
>     the worse, as would perlstyle, which is probably the closest thing
>     we have to a definition here, and which is a fairly relaxed
>     document.  We certainly don't want to get anywhere near to edit wars
>     over style.

Well, someone of authority will commit the changes to perlipc.pod with the=
=20
style that they see fit, and this will be accepted until perlipc.pod requir=
es=20
further updates. At the moment, however, my patch corrected many style and=
=20
best-practices issues based on the sources here:

http://perl-begin.org/tutorials/bad-elements/

>=20
> 2.  Best practices change over time.  When this document was first
>     written it didn't contain anything which, at the time, would have
>     been considered bad practice.  (I'm not sure it does even now,
>     though I suspect that even Tom would write the code differently
>     nowadays.)  This means the we would periodically need to update the
>     code in the examples, possibly using constructs recently added to
>     the language.  I'm not suggesting this is a particularly difficult
>     problem to solve should we want to, I'm more questioning whether we
>     want to.

Well, we should strive to update the document as much as we possibly have t=
he=20
resources for. I volunteered some of my time to update peripc up to 5.12.0=
=20
(and hopefully 5.14.0 and above) standards. I don't rule out that it will n=
eed=20
future updates, but it would still be better $X years from now than the =20
current perlipc is, which is no longer adequate *now*. So in the interests =
of=20
the present and the future, you should apply my patch or a similar one.

>=20
> 3.  And why should examples in the documents have to demonstrate best
>     practices anyway?  The purpose of most examples is not to explain
>     how to program Perl in general, but to describe some particular
>     aspect of the language.  It could be considered that any extraneous
>     code detracts from that goal.  That is why I would consider it
>     unnecessary to declare and initialise all the variables used, for
>     example.  Similarly, the addition of extra blank lines, which may be
>     useful in code itself, could simply prove distracting in a code
>     example where it might the more useful to be able to see all the
>     code on the same page as the text describing it.
>=20

The problem is that often people come to us for help with bad Perl code tha=
t=20
they lifted or written based on a bad (and likely old) source. We don't nee=
d=20
more badly written Perl code out there, and if we have a possibility to fix=
 it=20
for future generations to see, then it ought to be done. And we need to mak=
e=20
sure that the example code found in the Perl 5 core documentation also=20
demonstrates best practices, because if a fire has caught the firs, what wi=
ll=20
the moss on the wall say?

> 4.  It might even be considered advantageous to have numerous code
>     styles sprinkled around the official perl docs.  There are certainly
>     numerous Perl styles in the core, in CPAN modules and in the vast
>     majority of codebases where more than a couple of people have worked
>     on the code.  Why not in the documentation?

I don't mind having a small amount of style variation (see=20
http://www.joelonsoftware.com/articles/Wrong.html ), but we should not=20
sacrifice best practices in the core Perl 5 documentation. Naturally, if so=
me=20
of are blocks are:

[code]
if (COND) {
	.
	.
	.
}
[/code]

And some are:

[code]
if (COND)
{
	.
	.
	.
}
[code]

Then it would still be OK.

>=20
> 5.  My greatest concern, though, is that if someone has gone to the
>     effort to write a document, then they should have the right to
>     determine the style they will use not only in writing the text, but
>     in writing the code examples too.  Obviously if the code is wrong,
>     or is rendered incorrect by subsequent changes to the language, then
>     it needs to be updated.  Otherwise, I would be wary of making code
>     changes and would, in the spirit of perlpolicy.pod, prefer that such
>     changes only be made with the blessing of the original author, where
>     that is feasible.  In this case I think this should be feasible and,
>     if you have such a blessing, then I withdraw all my concerns about
>     this particular patch, although my general concerns still stand.

Well, I hereby ask the original author of perlipc.pod (Tom Christiansen I=20
believe) if he approves of such changes. Regardless of that, the documentat=
ion=20
has been written many years ago, and we should expect that it be kept up-to-
date, and it is licensed under a free-and-open licence which permits everyb=
ody=20
to make such changes. And in our case, I believe they are necessary, and ot=
her=20
people who've commented on my submissions seem to think so too.

Whatever "perldoc perlpolicy" say about the dual-life modules is not too=20
relevant to perlipc.pod.

Also see what I've written about it on my blog (for a different context) in=
 a=20
post titled "Changing the Seldon Plan":

http://community.livejournal.com/shlomif_tech/37969.html

(Gabor Szabo has written a follow-up to this here:
http://szabgab.com/blog/2009/11/1259431123.html ).

To sum up, we should not be afraid of modernising, fixing or refactoring ol=
d=20
open-source code, because this yields many short-term and long-term benefit=
s,=20
and we should not treat FOSS code as holy.

> So, in summary, whilst I'm very thankful for the changes you have made
> fixing mistakes, I fear that applying the stylistic changes would set a
> dangerous precedent.

How would it be dangerous? I didn't throw away the examples, and I've=20
preserved their spirit. I didn't even rewrite them completely from scratch,=
=20
but rather revamped them incrementally. I believe the spirit of the documen=
t=20
and most of its contents are preserved.

Regards,

	Shlomi Fish

=2D-=20
=2D----------------------------------------------------------------
Shlomi Fish       http://www.shlomifish.org/
"The Human Hacking Field Guide" - http://shlom.in/hhfg

<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 .