in reply to Any reason to have documentation-only *.pm file instead of *.pod for CPAN distro?

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.
  • Comment on Re: Any reason to have documentation-only *.pm file instead of *.pod for CPAN distro?

Replies are listed 'Best First'.
Re^2: Any reason to have documentation-only *.pm file instead of *.pod for CPAN distro?
by LanX (Saint) on Jan 02, 2025 at 15:57 UTC
    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]
Re^2: Any reason to have documentation-only *.pm file instead of *.pod for CPAN distro?
by Anonymous Monk on Jan 02, 2025 at 16:23 UTC

    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]

        The existence of a directory doesn't matter at all to how things are indexed. And subdirectories (or sub-packages) don't imply any relationship between namespaces. Claiming the package MCE::Core::Worker doesn't give you permissions on MCE::Core.

        Until the latest release, there was no MCE::Core package, only a .pod file. So it was not indexed, and had no permissions attached to it. It would have been possible for a bad actor to claim that namespace and upload any tarball they wanted for it.

        It is possible to control this through data in a META.json file, but usually that data is automatically generated. And it can still be confusing for a dist to claim it provides a module that doesn't actually exist because it's only a .pod file.

[reply]

In Section Seekers of Perl Wisdom