Re: pod::simple::text

[Shawn H Corey]

On Thu, 26 Jun 2014 15:40:14 +1200
Grant McLean gr...@mclean.net.nz wrote:

 On Wed, 2014-06-25 at 18:05 +, John E Guillory wrote:
  Hello,
 
  I thought I wasn’t this new to perl but …
 
  How does one use pod::simple::text to print out a section of POD,
  say the DESCRIPTION section? 
 
 Pod::Simple provides some core POD parsing functionality which is
 shared by a number of formatter classes.  There isn't any sort of
 query API that would allow you to specify which sections of the POD
 you want.
 
 If you do want to produce formatted plain-text output of just the
 DESCRIPTION section, then probably the easiest way is to slurp in all
 the POD source; use a regex to extract the section you want; and then
 pass that to a formatter:
 
   my($pod_source) =
   read_file($source_file) =~ 
   m{^(=head1\s+DESCRIPTION.*?)(?:^=head1.*)?\z}ms;
 
   my $parser = Pod::Simple::Text-new();
   $parser-parse_string_document($pod_source);
 
 The parser(/formatter) will write its output to STDOUT unless you call
 $parser-output_fh with an alternative filehandle.
 
 An alternative approach would be to subclass Pod::Simple::Text and
 maintain a flag indicating when the parser is 'in' the DESCRIPTION
 section and suppress all output when the flag is not set.
 Unfortunately the suppress all output bit is tricky since all the
 methods that produce formatted output write directly to the output
 filehandle.
 
 Regards
 Grant
 
 

Pod::Usage can extract sections for a POD. It come with perl.

#!/usr/bin/perl

use Pod::Usage;

# Documentation levels
my $DOC_USAGE = 0;
my $DOC_HELP  = 1;
my $DOC_VER   = 2;
my $DOC_MAN   = 3;

# --
# Subroutines

# --
#   Name: print_documentation
#  Usage: print_documentation( $documentation_level );
#Purpose: Print the usage, help, or man documentation.
#Returns: Does not return.
# Parameters: $documentation_level -- how much documentation to display.
# 0 == usage
# 1 == help
# 2 == version
# other == man
#
sub print_documentation {
  my $level = shift @_ || $DOC_USAGE;
  my @doc_options = (
# DOC_USAGE
{
  -exitval = 2,
  -verbose = 99,
  -sections = 'USAGE',
},
# DOC_HELP
{
  -exitval = 2,
  -verbose = 99,
  -sections = 'NAME|VERSION|USAGE|REQUIRED ARGUMENTS|OPTIONS',
},
# DOC_VER
{
  -exitval = 2,
  -verbose = 99,
  -sections = 'NAME|VERSION',
},
# DOC_MAN
{
  -exitval = 2,
  -verbose = 2,
},
  );

  # validate level
  $level =~ tr [0-9] []cds;
  $level ||= $DOC_USAGE;
  $level = $DOC_USAGE if $level = @doc_options;

  # print the documentation
  pod2usage( $doc_options[$level] );
}


-- 
Don't stop where the ink does.
Shawn

Re: pod::simple::text

[Jim Keenan]

 
 
 
On 06/25/14, John E Guilloryjo...@lsu.edu wrote:
 


Hello,

I thought I wasn?t this new to perl but ?;

How does one use pod::simple::text to print out a section of POD, say the 
DESCRIPTION section?

Thanks

 

John Guillory

Louisiana Library Network

#

Pod::Simple::Text (note the casing) is, as far as I can tell from the 
documentation, part of the plumbing of formatting POD as text and is probably 
not intended for the purpose you specified.  That is, it's not intended for 
end-user use.

I don't off-hand know how to print out just one section of POD as text.  But in 
general, you're starting point would be something like:

pod2text lib/List/Compare.pm  Compare.txt

Note: the pod-people mailing list is a very low volume mailing list for people 
concerned with the innards of Perl's POD mechanisms.  You'll probably get more 
responses in a location like perlmonks.org.

Thank you very much.
Jim Keenan

 

Re: pod::simple::text

[Grant McLean]

On Wed, 2014-06-25 at 18:05 +, John E Guillory wrote:
 Hello,

 I thought I wasn’t this new to perl but …

 How does one use pod::simple::text to print out a section of POD, say
 the DESCRIPTION section? 

Pod::Simple provides some core POD parsing functionality which is shared
by a number of formatter classes.  There isn't any sort of query API
that would allow you to specify which sections of the POD you want.

If you do want to produce formatted plain-text output of just the
DESCRIPTION section, then probably the easiest way is to slurp in all
the POD source; use a regex to extract the section you want; and then
pass that to a formatter:

  my($pod_source) =
  read_file($source_file) =~ 
  m{^(=head1\s+DESCRIPTION.*?)(?:^=head1.*)?\z}ms;

  my $parser = Pod::Simple::Text-new();
  $parser-parse_string_document($pod_source);

The parser(/formatter) will write its output to STDOUT unless you call
$parser-output_fh with an alternative filehandle.

An alternative approach would be to subclass Pod::Simple::Text and
maintain a flag indicating when the parser is 'in' the DESCRIPTION
section and suppress all output when the flag is not set.  Unfortunately
the suppress all output bit is tricky since all the methods that
produce formatted output write directly to the output filehandle.

Regards
Grant