-
Notifications
You must be signed in to change notification settings - Fork 77
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
POD error handling #216
Comments
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. |
@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. 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... |
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:
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
The text was updated successfully, but these errors were encountered: