On 02/09/2012 04:34 AM, David Cantrell wrote:
I doubt you'll ever see a distribution which has POD in both Foo/Bar.pm
and Foo/Bar.pod, because the perldoc tool will only see one or the other
when a user types 'perldoc Foo::Bar'.
+1 !
...by which I mean that I took this as a given: when Perl iterates
over @INC, it finds the first Foo/Bar.pm and loads that and goes no
further, THEREFORE I figure perldoc should do "the same thing":
Iterate over @INC, and for a given directory, if there's a
Foo/Bar.pod, render that, otherwise look in Foo/Bar.pm, which is the
.pm that the "use Foo::Bar" would use. (And if there's no docs in
that Foo/Bar.pm, then call it quits, aborting looping over @INC... I
guess?)
I think it's the simplest model.
And it means you can build a 1:1 mapping of
%Modulename_to_its_Filespec (as podwebserver does).
Now, in situations where there's docs in the .pod and in the .pm, I
say: ugh. The only things I would put in the .pm are things I would
mean to be accessible *only thru* the specific perldoc -F
filesystem-path-to-that-pm-file.pm ... in other words, maybe
programmery notes.
(I'll leave aside the bad situation where someone makes a version of
Foo including Foo::Bar and it's in a sitewide directory, but then they
make a newer version of Foo that doesn't provide a Foo/Bar.pm file,
but *does* have a Foo/Bar.pod file. In that case, "use Foo::Bar;"
gets you the old version of the code (because it's the first .pm file
in @INC!), but "perldoc Foo::Bar" gets you docs from the new dist.
But, well, to people writing modules, I say: "DON'T DO THAT!" More
generally, if you have a Foo/Bar.pm in one version of your module,
then later if you make a new dist that doesn't have any such file,
then you're just asking for version conflict problems-- so everything
goes bonkers, not just the perldoc searching mechanism.)
