chromatic said:
>
> Please explain to me, in detail sufficient for a three year old,
> precisely how:
>
> 1) POD can possibly behave any differently on my machine versus anyone
> else's machine, being non-executed text and not executed code
I'll assume the three-year-old is a particularly bright kid. :)
Let's say Joe Sysadmin wants to install the author's (a.k.a. "your")
module Useful::Example, and during the test-phase one of the POD tests
fail. There could be any number of reasons for this failure, including
but not limited to...
1) Joe's POD-analyzing module has a different/early/buggy notion of how
the POD syntax is supposed to be. This can be fixed by you in several
possible ways:
- The author ("you") can require a newer/better version of the
POD-analyzing module to be installed (So you're not keeping up with the
development on that front? Good thing your users can give you hints
about changes!)
- If there's no newer, you can contact the author of the POD-analyzer
and see if he can update his software (So your module is helping other
projects by finding edge cases or inconsistencies? Nice! Good thing your
users update the POD analyzer software quicker than you.)
2) The module actually has broken POD! POD converters scream in pain
everywhere! The generated HTML on search.cpan.org will be wrong! Google
will index the mistakes! Users searching for the functionality the
module supplies won't find it because the Google indexed the broken
documentation! OHNOEZ! What to do?
- Fix it, and release a new version.
3) Joe's POD-analyzing module is buggy (as in #1), but Joe cannot
upgrade that module for some reason. What to do?
- Make sure your POD tests ONLY run when a good version of the
POD-analyzer is installed, otherwise SKIP.
4) There's something wrong with your test. What to do?
- Fix it and release.
5) The POD specification is wrong. Or unclear about your use case. What
to do?
- Make the relevant author(s) aware of this bug, and tell them if you
think it's a bug in the documentation, the specification or something
else.
6) There's no bug!
- Yeah, riiiight. ;-)
....So it's not the POD that behaves differently, but /the surrounding
modules interpreting the POD/ that behave differently. But even if the
author's influence over Joe Sysadmin's installation is rather limited,
it's still the author's duty to make sure Joe can know (as best as
possible) that the module is in good shape. Now if Joe doesn't care
enough about Useful::Module to send a bug report (or send a failure
report to CPANTS), one can still hope someone else does it.
But you can be sure that if you _don't_ let the users run the tests,
then there's an even smaller chance you'll get that bugreport.
---- The short version ----
- All code has bugs - and if it has none now, someone will find (or
create, or define) them soon.
- The tests are code.
- The modules used by your tests are code.
- Build.PL and Makefile.PL is code
- The requirements sections in B.PL and M.PL are part of this code.
- It's a bug when build_requires for a module should say "0.42", but
instead says "0.41"
- Even your data and documentation (in whatever format you chose to
keep it) touches some sort of code - to parse it, convert it, analyze
it, check it or even to specify how it's supposed to look.
- In fact, we might as well treat everything as code, since we tend to
treat code somewhat respectfully (at least compared to how we treat
documentation.)
- So when we check if some documentation syntax is correct, we're
actually checking if some "code" is correct - not much unlike "use
warnings;" enables checks on the developer's use of Perl.
- In other words, "turning off" syntax checks (like Pod::Checker) in
order to spare the user of warnings/failures is much like turning off
"use warnings;" because the warnings make the developer think something
is wrong.
---- The super-short version :) ----
Turning off syntax checking of your POD is comparable to not turning on
warnings in your code. Now would you publish code developed without "use
warnings;"?
> 2) "Failures" in POD have any bearing on the use of the distribution,
> especially if an end-user has installed the distribution merely as a
> dependency and not as a developer
If that was the only kind of end-user, I'd agree - the bearing on usage
would be negligent. But it's not the only kind of end-user. I'll even be
brash and postulate that the non-developer end-user is one of the LESS
important ones, since he most likely won't interested in or capable of
taking part in the development community for that module.
But that doesn't mean the author should make it difficult to install
their modules cleanly... :)
> 3) False negatives are EVER acceptable in tests
If there's a false negative in a test, that's still a sign of a bug
somewhere. Maybe in the test itself? Or the dependencies? Or the build
system? Or some third-party module? Wherever it is, it's the author's
job to fix it, but he can't do that unless he first learns about it. :)
(I hope this helps explaining my rant a little. :)
- Salve
