POD ERRORS Hey! The above document had some coding errors, which are explained below

Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: POD ERRORS Hey! The above document had some coding errors, which are explained below by jasonk (Parson) on Aug 19, 2008 at 03:32 UTC
You might think it's vandalism, until the day when you are reading some documentation and saying to yourself "Why is it always the things I need to know that aren't in the documentation?" and then you see the pod errors notice at the bottom, and run `perldoc -m` instead, and discover that the documentation you need is there, it's just concealed by broken pod directives. www.jasonkohles.com We're not surrounded, we're in a target-rich environment!	[reply] [d/l]
Re: POD ERRORS Hey! The above document had some coding errors, which are explained below by Your Mother (Archbishop) on Aug 19, 2008 at 03:20 UTC
It's not vandalism, it's best practices as far as I'm concerned. I wish all software told you when you were making mistakes and made you look like a jerk till you fixed them. We'd have a lot less bad software and fewer jerks to boot.	[reply]
Re^2: POD ERRORS Hey! The above document had some coding errors, which are explained below by JavaFan (Canon) on Aug 19, 2008 at 10:07 UTC
It's one thing to tell the producer he makes a mistake, it's something else to mangle the product telling the consumer there's a mistake (of which many users will not have a clue how serious it is - specially not if it's done for programs, the user may have no clue what POD is, nor should he have to). Personally, I think it's not very useful to display the message at view time. And putting errors on STDOUT instead of STDERR is, IMNSHO, a big booboo. Errors belong on STDERR. That's why there is STDERR. IMO, the best times for displaying POD errors are at 1) "make test" time, and 2) "make dist" time.	[reply]
Re^3: POD ERRORS Hey! The above document had some coding errors, which are explained below by Your Mother (Archbishop) on Aug 19, 2008 at 14:57 UTC
I know where you're coming from but I want broken products to look broken. Not pretend otherwise. A message about bad Pod is a fairly good indicator, however minor, that the software author doesn't care about writing good software or keeping it maintained once it's out in the wild. So it's ultimately beneficial, if confusing to new comers, behavior for users. STDERR is fine but I'm tired of hackers who fill the error logs with a hundred lines a second because no one ever sees them. They mainly seem to find the behavior defensible because it's invisible and users are not savvy enough to see where it manifests in lost data, broken redirects, missing includes, etc. (Sidebar: I'm coming off a bit heavy but I truly appreciate Perl's forgiveness and flexibility in this regard.)	[reply]
Re^4: POD ERRORS Hey! The above document had some coding errors, which are explained below by JavaFan (Canon) on Aug 19, 2008 at 15:22 UTC
Re^5: POD ERRORS Hey! The above document had some coding errors, which are explained below by kyle (Abbot) on Aug 19, 2008 at 15:35 UTC
Some notes below your chosen depth have not been shown here
Re^5: POD ERRORS Hey! The above document had some coding errors, which are explained below by Your Mother (Archbishop) on Aug 19, 2008 at 16:48 UTC
Re^2: POD ERRORS Hey! The above document had some coding errors, which are explained below by Anonymous Monk on Aug 19, 2008 at 03:46 UTC
I wish all software told you when you were making mistakes and made you look like a jerk till you fixed them. But I am not making mistakes, I'm just reading someone elses. He use for example `=head1 NAME Foo - bar bar bar bar =head1 DESCRIPTION Foo bar bar bar bar =begin foo bar bar bar something foo bar bar bar =end foo bar bar bar =cut` [download] and get `NAME Foo - bar bar bar bar DESCRIPTION Foo bar bar bar bar POD ERRORS Hey! The above document had some coding errors, which are explaine +d below: Around line 14: '=end foo bar bar bar' is invalid. (Stack: =begin foo)` [download] What does pod2man, pod2text ... care about "foo bar bar bar" section. Another thing you can't turn it off (like it was before).	[reply] [d/l] [select]
Re^3: POD ERRORS Hey! The above document had some coding errors, which are explained below by Your Mother (Archbishop) on Aug 19, 2008 at 05:55 UTC
You've already made the right choice by bringing it up: don't suffer in silence. Try what the other anonymonk said first, upgrade. If it still turns up errors, file a bug with the author of the offending Pod. Then you'll be a Perl hero. Mine anyway.	[reply]
Re^4: POD ERRORS Hey! The above document had some coding errors, which are explained below by Anonymous Monk on Aug 19, 2008 at 06:03 UTC
Re^3: POD ERRORS Hey! The above document had some coding errors, which are explained below by Anonymous Monk on Aug 19, 2008 at 04:08 UTC
upgrade to Pod-Simple-3.07 (and Pod-Perldoc-3.14_07), seems to quiet most of those (the valid ones) `=begin foo bar bar this is valid =end foo =begin foo bar bar this is invalid =end foo bar bar` [download]	[reply] [d/l]