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

I have my POD embedded at the end of my package. However, I'd like to keep it totally separate from my code, if possible, by doing something like this: 

package Blah;

...
# code goes here

1;

__END__

# use some kind of incantation to pull in POD from separate file

[download]

I'm using Pod::Weaver and dzil.

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest Vicar";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

Replies are listed 'Best First'.
Re: Can POD be included from a seprate file using Pod::Weaver?
by davido (Cardinal) on Sep 02, 2019 at 19:00 UTC

    With Perl if you store a file alongside your module with the same name but with a .pod extension instead of a .pm extension, perldoc will find it. If you're packing for CPAN make sure your MANIFEST includes it, though.

    $ cat lib/Mymod.pm
package Mymod;

use strict;
use warnings;
use Exporter;
our @EXPORT = qw(greet);

sub greet {print "Hello\n"}

1;

.....


$ cat lib/Mymod.pod 
=pod

=head1 NAME

Mymod - Perl module to say hello.

=head1 SYNOPSIS

    use Mymod;
    greet();

=head1 DESCRIPTION

Example module.

=cut


.......

$ PERL5LIB='./lib' perldoc -T Mymod
NAME
    Mymod - Perl module to say hello.

SYNOPSIS
        use Mymod;
        greet();

DESCRIPTION
    Example module.

    [download]

    I can't seem to find where this feature is documented, but it's not hard to find it in use on CPAN.


    Dave

[reply]
[d/l]
[select]
      > I can't seem to find where this feature is documented

      Right at the beginning? ;)

      perldoc#DESCRIPTION

      perldoc looks up documentation in .pod format that is embedded in the perl installation tree or in a perl script

      Update

      But yeah it could be clearer stated. .pod is an extension POD the format.

      Cheers Rolf
      (addicted to the Perl Programming Language :)
      Wikisyntax for the Monastery FootballPerl is like chess, only without the dice

[reply]
[d/l]
[select]
Re: Can POD be included from a seprate file using Pod::Weaver?
by LanX (Saint) on Sep 02, 2019 at 18:53 UTC
    Call the separate file Blah.pod and put it into the same directory as Blah.pm .

    perldoc Blah will only show the docs in the separate file.

    No need for weaver.

    Cheers Rolf
    (addicted to the Perl Programming Language :)
    Wikisyntax for the Monastery FootballPerl is like chess, only without the dice

[reply]
[d/l]
[select]

      Perfect. That worked. I had the .pod file in a separate directory and was trying to "do" it into the main file. Thanks!

      $PM = "Perl Monk's";
      $MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest Vicar";
      $nysus = $PM . ' ' . $MCF;
      Click here if you love Perl Monks

[reply]

Back to Seekers of Perl Wisdom