Chaddaï Fouché writes:

> I'm quite surprised by this debate... To me it seems a clear rule that
> state that "if a line begin with "=" then it starts a POD section" is
> way easier to understand than "a line beginning by = will start a POD
> section except if it is in a Perl statement, or in a :to section, or
> in a string literal, etc...".

It is.  But that isn't the argument being made against it.

The point is that even knowing that simple rule is more complicated than
not having to know any rule at all.  Even knowing that there _is_ a rule
requires knowing that Pod exists, which shouldn't be a prerequisite for
starting your first Perl program; you can't learn everything at once, in

> The "Learning Perl 6" argument seems equally contrived to me since
> anyway you don't need POD to understand programming in Perl

Or rather, you didn't need that with Perl 5.

> and I never actually learned POD until I wanted to do a real module
> and document my little console utilities in Perl.

Sure.  But the 'Learning Perl' argument is this one, which you mentioned
later in your message

> The other "problem" is that if somehow a braindead guy (where would he
> get the idea from, I never saw such a style) put his "=" in first
> column expecting a assignment he won't get it... Seriously ?

Yes.  Personally I think that, on balance, the simplicity of the "what
is Pod?" rule is more of a gain than this awkwardness is a loss.  But it
is a completely valid argument.

Remember that also until Larry's recent proposal, this affected string
constants too -- and somebody might have anything in a multi-line

> Are you really allowing for such weirdness in introductory material to
> a Language course ?

The problem is that when teaching programming (I also used to be a Perl
5 trainer) you have to one part of the course first.  And whatever that
is, it really should be usable without relying on material that hasn't
yet been covered.

This means that when teaching the very basics of Perl a trainer has to
do one of:

* State the exception that C<=> is special in the first column of the
  source file -- thereby increasing the complexity of what users need to
  grasp in one 'chunk' when first covering variables, and distracting
  them from the core issue and sparking their curiosity with mention of
  this documentation language.

* Not mention it, and hope that nobody formats a line in a way which
  will be interpreted as Pod -- thereby causing much frustration in the
  rare cases where this does happen, making the learner in question
  irritated (with either the trainer for not mentioning it, or the
  language for having this exception).

Neither of those are ideal.

> You don't need to understand POD to read a program where POD is used :
> it's usually quite clear from the content where it is POD and where it
> is doc and each section that don't look like Perl is usually POD.

Yes.  But not if you've created unintentional Pod.


[Apologies for the lag in this.  I wrote 95% of the above 2 days ago --
before brian's similar message -- then got distracted and have only just
completed it.  But I thought it worth mailing anyway, to point that even
though I've argued on the opposite side from brian on this, I completely
acknowledge he has a valid point.]

Reply via email to