Softpanorama

May the source be with you, but remember the KISS principle ;-)
Contents Bulletin Scripting in shell and Perl Network troubleshooting History Humor

Perl POD documentation

News

See also

Recommended Books Recommended Links

Perl for Unix System Administrators

Perl Reference

Perl Language

Perl Xref Debugging Perl Style Regular expressions Debugging regular expressions Perl Programming Environment Pipes
Software Testing Program understanding Pretty Printing Sysadmin Horror Stories Perl Tips Humor Etc

Perl comes with its own documentation. The most straightforward and widely preferred way to read it is by means of the perldoc command line utility. It will give access to specific perl manpages (e.g.: perlsyn for Perl syntax or perlop for Perl operators) as well as to the documentation for individual functions and faq entries: it supports a large number of command line switches that are described in its own documentation. To access the latter just issue the following command at your shell's prompt:

perldoc perldoc

For some tips about where to look for some particular information, see brian_d_foy's Perl documentation documentation tutorial.

To put it briefly, however, most times you will want to use perldoc as in one of the following examples:

HTML

The language used by perldoc, POD makes it easy to render the documentation in a variety of target formats, including HTML. Some Perl distributions, most notably ActiveState's ActivePerl, a very popular one under Windows, come with ready made HTML documentation, which some find easier to read and walk through.

An HTML version of the documentation is also available on the web at http://perldoc.perl.org/ and some other locations. As such, it can be searched through with Google and the above mentioned tutorial contains some specific examples about how to do so.

Grep

Some people prefer to use a grep or grep-like utility to search specific stuff in the POD documentation installed on their computers, and one can indeed use such an approach when everything else fails.

Other options include:

Other options

One additional possibility is to use the perlindex utility, which is "a program to index and search the perl documentation."

The tkpod standalone Tk POD viewer from Tk::Pod (which is a GUI for viewing and browsing Perl's POD documentation) also provides an interface to perlindex if it is installed, and its features additionally include:

Yet another alternative to perldoc is Pod::Webserver, a minimal web server which serves local Perl documentation: with it one can browse all the docs available on the machine it runs on with a web browser.

NEWS CONTENTS

Old News

Plain Old Documentation in 5 minutes - Juerd's site

[Nov 13, 2017] Strip Pod as Pod from Perl file - Stack Overflow

Nov 13, 2017 | stackoverflow.com

Håkon Hægland ,Nov 2, 2014 at 12:10

I am trying to extract the Pod documentation from a Perl file. I do not want to convert the documentation to text as is done by Pod::Simple::Text . I just want the Pod text as Pod text, such that I can feed it into Pod::Template later. For example:
use warnings;
use strict;
use Pod::Simple::Text;
my $ps=Pod::Simple::Text->new();
my $str;
$ps->output_string( \$str );
$ps->parse_file($0);
print $str;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

This will print the Pod as text. Is there a CPAN module that can give me the Pod text, that is:

=head1 SYNOPSIS

prog [OPTIONS]

instead?

Update

The solution should be able to handle Pod docs in strings, like

my $str = '__END__

=head1 SYNOPSIS';

Miller ,Nov 2, 2014 at 18:42

This can be done using PPI :
use strict;
use warnings;

use PPI;

# Slurp source code
my $src = do { local ( @ARGV, $/ ) = $0; <> };

# Load a document
my $doc = PPI::Document->new( \$src );

# Find all the pod within the doc
my $pod = $doc->find('PPI::Token::Pod');
for (@$pod) {
    print $_->content, "\n";
}

=comment
Hi Pod
=cut

1;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

Outputs:

=comment
Hi Pod
=cut

=head1 SYNOPSIS

prog [OPTIONS]

Håkon Hægland ,Nov 3, 2014 at 12:51

Thanks for this great solution. It even works with Pod docs embedded in strings, like my $str='__END__ =head1 SYNOPSIS';Håkon Hægland Nov 3 '14 at 12:51

Tim ,Nov 2, 2014 at 13:58

Use the -u option for perldoc . This strips out the POD and displays it raw.

If you want to extract the POD from within a Perl program, you could do something like this:

my $rawpod;
if (open my $fh, '-|', 'perldoc', '-u', $filename) {
  local $/;
  my $output = <$fh>;
  if (close $fh) {
    $rawpod = $output;
  }
}

If you really don't want to run perldoc as an executable, you might be interested that the perldoc executable is a very simple wrapper around Pod::Perldoc which you might want to consider using yourself.

Håkon Hægland ,Nov 3, 2014 at 12:55

Thanks, but it does not work with Pod docs embedded in strings. See my updated question for an example.. – Håkon Hægland Nov 3 '14 at 12:55

Tim ,Nov 3, 2014 at 18:54

Well, if you change the question, it's not that surprising that a given answer no longer works. I'm pleased you've found a solution to your new question. – Tim Nov 3 '14 at 18:54

Håkon Hægland ,Nov 5, 2014 at 6:40

The problem with perldoc is that there is a bug, so it thinks Pod embedded in a string belongs to the document. – Håkon Hægland Nov 5 '14 at 6:40

Calle Dybedahl ,Nov 2, 2014 at 12:54

Pod::Simple::SimpleTree will give it to you as a parse tree. You can convert that back to POD source easily enough.

toolic ,Nov 2, 2014 at 13:51

+1 if you provide a runnable code example. – toolic Nov 2 '14 at 13:51

[Nov 13, 2017] Strip Pod as Pod from Perl file - Stack Overflow

Nov 13, 2017 | stackoverflow.com

Håkon Hægland ,Nov 2, 2014 at 12:10

I am trying to extract the Pod documentation from a Perl file. I do not want to convert the documentation to text as is done by Pod::Simple::Text . I just want the Pod text as Pod text, such that I can feed it into Pod::Template later. For example:
use warnings;
use strict;
use Pod::Simple::Text;
my $ps=Pod::Simple::Text->new();
my $str;
$ps->output_string( \$str );
$ps->parse_file($0);
print $str;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

This will print the Pod as text. Is there a CPAN module that can give me the Pod text, that is:

=head1 SYNOPSIS

prog [OPTIONS]

instead?

Update

The solution should be able to handle Pod docs in strings, like

my $str = '__END__

=head1 SYNOPSIS';

Miller ,Nov 2, 2014 at 18:42

This can be done using PPI :
use strict;
use warnings;

use PPI;

# Slurp source code
my $src = do { local ( @ARGV, $/ ) = $0; <> };

# Load a document
my $doc = PPI::Document->new( \$src );

# Find all the pod within the doc
my $pod = $doc->find('PPI::Token::Pod');
for (@$pod) {
    print $_->content, "\n";
}

=comment
Hi Pod
=cut

1;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

Outputs:

=comment
Hi Pod
=cut

=head1 SYNOPSIS

prog [OPTIONS]

Håkon Hægland ,Nov 3, 2014 at 12:51

Thanks for this great solution. It even works with Pod docs embedded in strings, like my $str='__END__ =head1 SYNOPSIS';Håkon Hægland Nov 3 '14 at 12:51

Tim ,Nov 2, 2014 at 13:58

Use the -u option for perldoc . This strips out the POD and displays it raw.

If you want to extract the POD from within a Perl program, you could do something like this:

my $rawpod;
if (open my $fh, '-|', 'perldoc', '-u', $filename) {
  local $/;
  my $output = <$fh>;
  if (close $fh) {
    $rawpod = $output;
  }
}

If you really don't want to run perldoc as an executable, you might be interested that the perldoc executable is a very simple wrapper around Pod::Perldoc which you might want to consider using yourself.

Håkon Hægland ,Nov 3, 2014 at 12:55

Thanks, but it does not work with Pod docs embedded in strings. See my updated question for an example.. – Håkon Hægland Nov 3 '14 at 12:55

Tim ,Nov 3, 2014 at 18:54

Well, if you change the question, it's not that surprising that a given answer no longer works. I'm pleased you've found a solution to your new question. – Tim Nov 3 '14 at 18:54

Håkon Hægland ,Nov 5, 2014 at 6:40

The problem with perldoc is that there is a bug, so it thinks Pod embedded in a string belongs to the document. – Håkon Hægland Nov 5 '14 at 6:40

Calle Dybedahl ,Nov 2, 2014 at 12:54

Pod::Simple::SimpleTree will give it to you as a parse tree. You can convert that back to POD source easily enough.

toolic ,Nov 2, 2014 at 13:51

+1 if you provide a runnable code example. – toolic Nov 2 '14 at 13:51