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

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.

Comment on Re^2: POD ERRORS Hey! The above document had some coding errors, which are explained below

Replies are listed 'Best First'.
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
I understand your first couple of lines, although I do not agree with them. However, I don't get the second part of your rant. What do error logs have to do with it? And why it's it the "hackers" fault of noone looks at the error log? First of all, neither "make install", nor "perldoc" redirects STDERR to an error log. Furthermore, if you use software of mine, and said software is setup (either by itself, a redirect by the program calling it, a syslog config or something) to redirect its errors to a file, and you don't look at it, who is to blame? You or me?	[reply]
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
I can't say for sure what Your Mother meant, but the reference to error logs made me think of a web server's error log. I've worked at more than one place where the web server error log was perpetually filling with warning messages from sloppy code and other debugging debris.	[reply]
Re^6: POD ERRORS Hey! The above document had some coding errors, which are explained below by Anonymous Monk on Aug 20, 2008 at 05:30 UTC
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
I conflated two experiences, work + personal dev, and shouldn't have. At work, it's often the tech manager who is responsible for choosing to ignore errors. In personal dev, it's a free enough world so blame doesn't come into it exactly. Documentation is for end users, not for the installation process. The end user never sees STDERR so the only chance they get to know something is wrong is if it's included with the document. Like jasonk notes, it can be a clue that the documentation didn't even get built. I'm not looking for blame, I'm looking for confirmation that a software package has some integrity and care applied to it. That process does not start at install/make time. For me it starts at browse-CPAN time. I like knowing a distribution is likely garbage or abandonware before I spend 5 hours finding out by trying to use it in a project. Again, I love having all the options for errors and development. It really wasn't meant as a rant; maybe an overzealous and somewhat spastic defense of the Pod tools' behavior.	[reply]