How do I get Perl POD in string and print it in page?

Question

I have a POD document. Now, I want to convert that POD to a parsed section like usage/description and get it in a string.

Why not pod2usage?

This doesn't help me to get the output in string but in STDOUT/file. I am stressing on the point "getting it in string", because I want to display the POD in "pages" if the length exceeds screen length. pod2usage doesn't print them in pages :(

Can somebody tell me which module to use for this purpose?

Answer 1

Pod::Usage, which is referenced on the bottom of the pod2usage man page.

Answer 2

From the Pod::Parser documentation:

Alternatively, an IO::String object is also accepted as an output file handle.

So this is perfectly legal:

#!/usr/bin/perl
use strict;
use IO::String;
use Pod::Text;
my $buffer;
my $io = IO::String->new($buffer);
my $parser= Pod::Text->new (sentence => 0, width => 78);
$parser->parse_from_file('/usr/share/perl5/Net/Jabber.pm',$io);
print $buffer;

On the other hand, remember that you can capture the output of any command using backticks, e.g.

$text = `/usr/bin/pod2usage /usr/share/perl5/Net/Jabber.pm`;

or qx{} for clarity:

$text = qx{/usr/bin/pod2usage /usr/share/perl5/Net/Jabber.pm};

Answer 3

You don't have to do all of the Pod parsing yourself; most of it is done already with Pod::Simple. You can write a short subclass to do whatever you need. I have a chapter in Mastering Perl that goes into the details, but you can also look at my Pod::Perldoc::TOC module to see a short example.

Basically, you handle the =head1 elements, but skip the ones that aren't SYNOPSIS. Once you run into the right =head1, set a flag and process the section until you run into another =head1, at which point you stop parsing. You can do anything you like between the =head1's, including appending to a variable.