Re: .pod files

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.)