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...". The "Learning Perl 6" argument seems equally contrived to me since anyway you don't need POD to understand programming in Perl and I never actually learned POD until I wanted to do a real module and document my little console utilities in Perl. 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. Even if you never heard of POD the first few samples would be a dead giveaway that those weird "things" are actually documentation and not code (it's my experience speaking here).
I seriously doubt most programmer will start including POD section in confusing places because now they can do it, so the situation should not be any different from before. And if some do it, hell, I seriously doubt that their program would be in the scope of the beginning of "Learning Perl 6" !! You didn't put "-+-" there in previous versions, did you ? 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 ? Are you really allowing for such weirdness in introductory material to a Language course ? So in my opinion, it would be fine to let slip that you can also create some kind of comment/doc by putting a = in the first column in the first chapter, and let the subject of POD for a later chapter. Of course some of you have far more experience teaching languages, but as a language _student_ I don't feel this would be any inconvenience, in fact I would have been very happy if all the Perl5 rules were that easy. -- Jedaï
