$ cat hello.pl

=head1 NAME

hello.pl - say hello

=head1 DESCRIPTION

Example: perl hello.pl

=cut

use warnings;
use strict;

print "hello\n";
$
$
$ perldoc hello.pl

HELLO(1)              User Contributed Perl Documentation             
+HELLO(1)



NAME
       hello.pl - say hello

DESCRIPTION
       Example: perl hello.pl



perl v5.8.9                       2011-07-22                          
+HELLO(1)
[download]

In the CB, someone also pointed to Documenting Code -> POD in 5 minutes

Practically every production-ready Perl script or module has the POD embedded within the source code itself. There are various strategies for doing this; embed it intermixed with code, or embed it after the end of the code. There are arguments for doing it either way, so rather than to hijack the thread toward that topic I'll move on to why I replied. I only mention it here so you'll know ahead of time what to look for.

Since POD is embedded in almost every piece of Perl code that ships with the Perl distribution, you have hundreds of examples to choose from. Literally view the contents of a Perl script or module that shipped with Perl. When you finish that one, look at another. ;)

Then if you want more help, install Module::Starter, create a temporary folder, enter that folder, and type module-starter --module=Mytest --author='your name' --email=your@email. A little module stub will be created in your temp directory, and if you view the source of Mytest.pm you will find a POD template embedded in it. It's pretty basic, but you can use it as a starting point. In fact, I don't do this myself, but it would be pretty easy to put at the top of it your boilerplate "use strict; use warnings;" stuff, push the embedded POD to the bottom, remove anything module-specific, and use it as a template for any script you write.

Thank You but I don't think you quite understand my question. I know how to make a POD, I just don't know how to open the POD as a, for example, perldoc.
perl.j-----A Newbie To Perl

Silly me for reading a question about writing POD, and not understanding that it's really a question about displaying POD. What's wrong with "perldoc Mytest.pl"?

Perhaps you could explain a little better: Are you trying to compose POD, output POD to a file, display POD? Is perldoc --help useful info for you?




Dave

$ perldoc -l CGI
/home/moritz/perl5/perlbrew/perls/perl-5.14.1/lib/5.14.1/CGI.pm
$ less /home/moritz/perl5/perlbrew/perls/perl-5.14.1/lib/5.14.1/CGI.pm
[download]

You might also find podchecker useful.

I'm sorry I don't quite understand what you're saying.
perl.j-----A Newbie To Perl

It seems quite plain, in context: he's saying "Read some samples -- from among your .pm files -- and here's one way to do it."

Until you've done that, and until you have carefully read the docs cited above, you haven't done your part in this learning partnership.

If you know "how to make headings and links and etc..." then just do that. Save your Perl script or module or whatever it is you're writing the POD as part of. Then just run:

perldoc my_file_name
[download]

For example, I put POD in a script I call dtach.pl. From the command line, I just type:

perldoc dtach.pl
[download]

And the POD is displayed nice and formatted as perldoc pages.

If you're looking for something else, there are a bunch of pod2xxx utilities, where xxx = html, ps, man, etc... to convert POD to output files of the specific utility's type. I use pod2html pretty regularly to post POD pages on my web site.

It didn't work. My file is called first.pod. I got the error message "No documentation found."
perl.j-----A Newbie To Perl