Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

I noticed there are a few cases on CPAN (HTML::Template::FAQ is one of them) where authors have chosen to place their FAQ, Tutorial or Extended Docs, etc. -- too long/distracting to keep in Code.pm -- into a separate *.pm rather than *.pod file. Any advantage of one over another? Or is this choice insignificant (TIMTOWTDI, etc.)?

Replies are listed 'Best First'.
Re: Any reason to have documentation-only *.pm file instead of *.pod for CPAN distro?
by Haarg (Priest) on Jan 02, 2025 at 15:46 UTC
    Pod files aren't indexed by PAUSE or some other tools, so they can't be installed by name using some tools. They also don't get permissions attached, so someone else could take over the namespace. pm files can also have a parseable version, which can help tracking module changes.
[reply]
      You're saying that .pod files can't be installed out of context, but still come with the distribution?

      Unless I misunderstand you, that's a feature not a bug.

      Regarding taking over the namespace, having equally named .pod and .pm should be safe in this respect.

      update

      to better understand the namespace issue

      Two dists

      • Foo with Foo/lib/FAQ.pod
      • Foo::FAQ with Foo/FAQ/lib/FAQ.pm
      could clash?

      Cheers Rolf
      (addicted to the Perl Programming Language :)
      see Wikisyntax for the Monastery

[reply]
[d/l]
[select]

      Oh, interesting, thanks. Actually, one of the counter-examples where I found *.pod but expected to see *.pm while doing research myself, was MCE::Core. So, then, yes, I tried just now:

      >cpanm --test-only MCE::Core
! Finding MCE::Core on cpanmetadb failed.
! Finding MCE::Core () on mirror http://www.cpan.org failed.
! Couldn't find module or a distribution MCE::Core

      [download]

      So... someone evil can hijack the namespace?

[reply]
[d/l]
[select]

        Thank you, Anonymous Monk. The Core directory exists in MCE since the first release. I created MCE 1.901 adding the missing pm file.

        module : MCE::Core
version: 1.901
in file: lib/MCE/Core.pm
status : indexed

        [download]
[reply]
[d/l]
[reply]
[d/l]
Re: Any reason to have documentation-only *.pm file instead of *.pod for CPAN distro?
by LanX (Saint) on Jan 02, 2025 at 15:35 UTC
    Many just don't know .pod exists and works with perldoc and any other tool.

    FWIW: I have projects where I maintain equally named XXX.pm and XXX.pod files.

    Cheers Rolf
    (addicted to the Perl Programming Language :)
    see Wikisyntax for the Monastery

[reply]

Back to Seekers of Perl Wisdom