POD error handling

[ntyni]

Since podlators 2.5.0 (perl 5.17.8, Pod::Man 2.27), Pod::Man has supported three different ways of handling POD errors. The old way of advertising them in the generated manual page (in a POD ERRORS section) is still the default for Pod::Man, as the others are not really suitable for libraries, but the pod2man script now defaults to dying on POD errors. The third option is to output warnings on stderr during the conversion.

Quoting Russ Allbery in https://rt.cpan.org/Public/Bug/Display.html?id=39007:

The primary argument for doing this is that POD errors are primarily
of interest to the author of the POD, not to thte end-user, but the POD
ERRORS section in an installed man page tells the user about things they
can't do anything about.

There's also some resulting discussion on the perl5-porters list at http://www.nntp.perl.org/group/perl.perl5.porters/2008/09/msg139898.html.

Now, ExtUtils::MakeMaker contains its own implementation of pod2man (in ExtUtils::Command::MM), which is still using the default Pod::Man behaviour. The above rationale applies to that one as well. Please consider making it match the "real" pod2man behaviour by dying on POD errors (errors => 'die' in the Pod::Man constructor call), or if that's too intrusive for CPAN, at least output a warning on stderr (errors => 'stderr') so the author has a chance to notice it during the build.

Thanks for your work,

Niko Tyni ntyni@debian.org

[karenetheridge]

Agreed, we should definitely warn when errors are encountered; this is reasonable for end-user installs as well as on the author side.

There's been several cases where warnings ought to be vigorously flagged for the author to see, so I'd like to propose that EUMM operate in a stricter mode on the authoring side and error out instead of merely warning, to ensure that errors are caught as soon as possible.

[dolmen]

@ntyni End user must not endure install failures just because of POD errors.

It is the responsibility of the POD author to ensure it is correct, but for that he is dependent on the capabilities of the checking tool, and we can not also blame an author 10 years later just because the POD checking tool is stricter now. See RT#62498 for some history on the matter.
So hard failure (die) in EUMM is not an option.

The best practice for authors is to have an author test that uses Test::Pod, and that will not run (or at least never fail) on the end-user machine. See the specification of environment variables for testing contexts in the Lancaster Consensus. This reminds me I have to submit a doc patch to Test::Pod to spread this best practice...