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 parallel. > 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 string. > 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. Smylers [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.]
