No good deed goes unpunished

Wanting to be helpful, I wrote some POD for the shiny new module and CGI that I'd created. All appeared well until the mysterious error

Missing right curly or square bracket at foo.pl line 281, at end of line\nsyntax error at foo.pl line 281, at EOF\n

started appearing in the error log.

I checked with IRC, I ran the source code through perltidy (no changes -- it was already clean), I paged through my dog-eared Camel. Finally I was down to thought experiments. What had I changed or added recently? Why, nothing but POD, your honour, honest.

However, being an irregular PODder, I wasn't quite up on my syntax, and I had ended both blobs of POD with the =end tag and not a =cut tag. Sure enough, a quick check with Test::Pod confirmed the dastardly error.

So, if this is news to you, please turn to page 949 of your Camel and add the following after the second item on the page:

Also check your POD -- you may be missing a =cut at the end of your file!

Thank you. Class dismissed.

Alex / talexb / Toronto

"Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds

Update: And podchecker can also be used to check that the POD's OK, as Anonymonk points out.

Comment on No good deed goes unpunished Select or Download Code

Replies are listed 'Best First'.
Re: No good deed goes unpunished by perrin (Chancellor) on Jul 31, 2009 at 19:46 UTC
Inline POD is the devil. I like to put my POD at the end, after a __END__.	[reply]
Re^2: No good deed goes unpunished by talexb (Chancellor) on Aug 04, 2009 at 14:02 UTC
Inline POD is the devil. I like to put my POD at the end, after a __END__. Technically, my POD was after the `1;`, so while it may have sounded like inline POD (which I agree is absolutely the devil), it wasn't. And I'm not a fan of using the `__END__` tag -- personal preference. Alex / talexb / Toronto "Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds	[reply] [d/l] [select]
Re^3: No good deed goes unpunished by perrin (Chancellor) on Aug 06, 2009 at 14:14 UTC
You don't have to like __END__, but it does solve problems with POD messing up code. Nothing after it is parsed by perl.	[reply]
Re: No good deed goes unpunished by Anonymous Monk on Jul 31, 2009 at 18:18 UTC
and podchecker	[reply]
Re: No good deed goes unpunished by JavaFan (Canon) on Jul 31, 2009 at 23:07 UTC
So, you write POD and you don't even look at the output of pod2text? Forgetting a =cut will put a lot more into the produced documentation, it's not something you'll miss by even only glancing at the output of whatever podlator you use. That's like shipping code without even bothering to see whether it compiles.	[reply]
Re^2: No good deed goes unpunished by JadeNB (Chaplain) on Aug 03, 2009 at 05:31 UTC
This seems unnecessarily harsh. It sounds like talexb was testing his code, found errors, and tracked down the source. There's no clear indication that anything flawed was released, and the error was fixed; so why complain that he tested the code before the POD? I'm particularly happy with No good deed goes unpunished because I was, literally, just this minute reading through perlpod and wondering "Do I have to end a `=begin`/`=end` block with a `=cut`?", but feeling too lazy to test.	[reply] [d/l] [select]
Re^3: No good deed goes unpunished by dsheroh (Monsignor) on Aug 03, 2009 at 17:42 UTC
What had I changed or added recently? Why, nothing but POD, your honour, honest. That reads to me like talexb had working code, added pod, then noticed that the code had stopped working and started tracking it down as a code problem without at any point having looked at the documentation created by the pod he'd added. I have to agree with JavaFan's reaction of "why are you bothering to add pod if you're not going to run pod2text over it and see what it outputs?"	[reply]
Re^4: No good deed goes unpunished by talexb (Chancellor) on Aug 04, 2009 at 13:59 UTC
Re^2: No good deed goes unpunished by talexb (Chancellor) on Aug 04, 2009 at 13:51 UTC
So, you write POD and you don't even look at the output of pod2text? Apparently, yes. But that's going to change -- one of the things that I thought about as I renovated my basement this weekend was how to check for that particular problem. My solution is to make it one of the steps in the `Makefile`, so that if it fails, the package isn't created. Hey, if I'm still learning after ten years with the language, that's better than declaring I know everything there is to know and closing my mind. Did that once with C and had a pretty rude awakening. But that's a story for another time. Thanks for the feedback. Alex / talexb / Toronto "Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds	[reply] [d/l]