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.)
Re: .pod files
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'. Thank you David, this is very useful. My conclusion is that it is not explicitly forbidden, but it is not supported in practice. Florent
.pod files
Dear all, I had a look at the perlsyn, perldoc and perldocspec documents but cannot seem to find the answer to the following questions. The POD content of a module can be written into its Perl file or into a separate .pod file. There are quite a few examples of modules around that use one method or the other. However, is it allowed to put part of a POD documentation into the .pod file and the other part in corresponding Perl files? In other words, if a .pod file exists for a module, should I bother looking for POD into the corresponding Perl file? Are there examples of Perl modules using POD in a .pod and .pm file or is it simply a theoretical case? Thank you, Florent
Re: .pod files
On Thu, Feb 09, 2012 at 11:33:21AM +1000, Florent Angly wrote: The POD content of a module can be written into its Perl file or into a separate .pod file. There are quite a few examples of modules around that use one method or the other. However, is it allowed to put part of a POD documentation into the .pod file and the other part in corresponding Perl files? In other words, if a .pod file exists for a module, should I bother looking for POD into the corresponding Perl file? Are there examples of Perl modules using POD in a .pod and .pm file or is it simply a theoretical case? 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'. Having POD in both .pm and .pod files in a distribution is fairly common, but in that case the .pm file's POD will typically tell you how to use the module, and the .pod file's POD will normally be either documentation of internals, or explain how to sub-class or extend - and, of course, they'll have different names: perldoc Foo::Bar # tell the user how to use Foo::Bar, comes from .pm file perldoc Foo::Bar::Extending # how to extend Foo::Bar, comes from .pod file -- David Cantrell | Hero of the Information Age You are so cynical. And by cynical, of course, I mean correct. -- Kurt Starsinic
Re: how to use L in the env with deeply nested .pod files
At 12:45 2002-01-16 +0800, Stas Bekman wrote: In the new mod_perl documentation we have many .pod files and they are deeply nested. For example: ../docs/2.0/devel/testing/testing.pod ../docs/2.0/devel/benchmarks/benchmarks.pod ../docs/2.0/user/coding/coding.pod ../docs/2.0/user/compat/compat.pod ../docs/2.0/user/design/design.pod ../docs/2.0/user/overview/overview.pod ../docs/2.0/world/templates/choosing.pod ../docs/1.0/faqs/mod_perl_api.pod ../docs/1.0/faqs/mod_perl_cgi.pod I want to be able to reference documents and have them properly hyperlinked when HTML is rendered. It's possible that there will be more than one pod file with the same name. The only uniqueness is ensured by the path the pod resides in. e.g. we have 1.0/user/install.pod and 2.0/user/install.pod. How would you tackle this problem? When I want to reference install.pod for modperl 1.0 from install.pod for modperl 2.0, do you say: L1.0/user/install/intro and look for the matching pod in the common search path. Or should it be better L../../1.0/user/install/intro I think that Pod, in its current form, makes no provision for either of these things per se. That's unless urls like file:../../whatever are legal -- and if they are, then it's just a matter of doing Lfile:../../whatever and hoping that pod2html (which is currently a hideous wreck) supports that -- and that these things are to accessed across a file: scheme. I know, it's ugly. Barring that, you may just have to do LWhatever::Thing::1.0::user::install/intro That's if I understand your problem correctly. -- Sean M. Burke[EMAIL PROTECTED]http://www.spinn.net/~sburke/
how to use L in the env with deeply nested .pod files
In the new mod_perl documentation we have many .pod files and they are deeply nested. For example: ../docs/2.0/devel/testing/testing.pod ../docs/2.0/devel/benchmarks/benchmarks.pod ../docs/2.0/user/coding/coding.pod ../docs/2.0/user/compat/compat.pod ../docs/2.0/user/design/design.pod ../docs/2.0/user/overview/overview.pod ../docs/2.0/world/templates/choosing.pod ../docs/1.0/faqs/mod_perl_api.pod ../docs/1.0/faqs/mod_perl_cgi.pod I want to be able to reference documents and have them properly hyperlinked when HTML is rendered. It's possible that there will be more than one pod file with the same name. The only uniqueness is ensured by the path the pod resides in. e.g. we have 1.0/user/install.pod and 2.0/user/install.pod. How would you tackle this problem? When I want to reference install.pod for modperl 1.0 from install.pod for modperl 2.0, do you say: L1.0/user/install/intro and look for the matching pod in the common search path. Or should it be better L../../1.0/user/install/intro Thanks. _ Stas Bekman JAm_pH -- Just Another mod_perl Hacker http://stason.org/ mod_perl Guide http://perl.apache.org/guide mailto:[EMAIL PROTECTED] http://ticketmaster.com http://apacheweek.com http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
