Beefy Boxes and Bandwidth Generously Provided by pair Networks
The stupid question is the question not asked
 
PerlMonks  

Showing the right POD via Pod::Usage

by skx (Parson)
on Jan 24, 2013 at 22:39 UTC ( #1015240=perlquestion: print w/ replies, xml ) Need Help??
skx has asked for the wisdom of the Perl Monks concerning the following question:

I've written a program which is distributed as a single script, but implemented as a series of modules. Distributing the script as one file avoids the need to "install", or mess with include-paths.

Unfortunately this means that my script looks like this:

# ... pod for module1 # ... code for module1 # ... POD for module2 # .... code for module2 # package main # pod # code

This screws up my preferred usage of POd::Usage, as it shows the pod for all the script. I've read the documentation for Pod::Usage, where it suggets using Pod::Find and the current package (__PACKAGE__) but I cannot make it work, as the following demonstrates.

Is there a simple solution, or am I out of luck?

Test program follows:

#!/usr/bin/perl -w use strict; use warnings; use Getopt::Long; use Pod::Find qw(pod_where); use Pod::Usage; =head1 NAME Foo - Do something. =cut =head1 SYNOPSIS use strict; use Foo; my $f = Foo->new(); $f->doStuff(); =cut =head1 DESCRIPTION This class encapsulates stuff. =cut package Foo; =head2 new Constructor =cut sub new() { my ( $proto, %supplied ) = (@_); my $class = ref($proto) || $proto; my $self = {}; bless( $self, $class ); return $self; } =begin doc Do stuff =end doc =cut sub do_stuff() { } =head1 NAME My Script - Do something =cut =head1 SYNOPSIS Usage: $0 [options] options --help Show the help --man Show the manual. =cut =head1 DESCRIPTION This is the utility to do stuff .. It uses the Foo module internally. =cut package main; # # Configuration variables # my %CONFIG; # # Parse the command line. # exit if ( !Getopt::Long::GetOptions( # Help options "help", \$CONFIG{ 'help' }, "manual", \$CONFIG{ 'manual' }, ) ); Pod::Usage::pod2usage() if ( $CONFIG{ 'help' } ); Pod::Usage::pod2usage(-verbose => 2 ) if ( $CONFIG{ 'manual' } ); print "I am alive\n"; exit( 0 );
Steve
--

Comment on Showing the right POD via Pod::Usage
Select or Download Code
Re: Showing the right POD via Pod::Usage
by Athanasius (Monsignor) on Jan 25, 2013 at 02:36 UTC

    The following is a kludge, but may be worth a try:

    Change the second:

    =head1 SYNOPSIS
    to (say):
    =head1 MAIN

    and then invoke pod2usage as:

    Pod::Usage::pod2usage( pod2usage(-verbose => 99, -sections => [ qw(MAIN) ] ) ) if ( $CONFIG{ 'help' } );

    See -sections in the “Arguments” section of Pod::Usage.

    Hope that helps,

    Athanasius <°(((><contra mundum Iustus alius egestas vitae, eros Piratica,

      Renaming the sections would be a simple solution that hadn't occurred to me, thanks.

      (I've gone the other way and used a __DATA__ block to hold it).

      Steve
      --
Re: Showing the right POD via Pod::Usage
by Anonymous Monk on Jan 25, 2013 at 03:10 UTC

      Right now I have N files, each of which contains "pod" + "code". To combine them I just use cat.

      Moving the pod away from the code feels like a bad idea.

      Steve
      --

        Right now I have N files, each of which contains "pod" + "code". To combine them I just use cat.

        Moving the pod away from the code feels like a bad idea.

        Keep pod however you want, but don't deploy pod, but don't ship pod, but don't give the end user pod he doesn't care about, don't pack the pod that isn't meant for end user, strip it for deployment, strip it for packing, strip it don't ship it

        When I'm using http://cpanmin.us/ I don't care about the modules it uses

Re: Showing the right POD via Pod::Usage
by Anonymous Monk on Jan 25, 2013 at 03:14 UTC

    Pack the script pod in __DATA__ and use  -input => \*DATA

    "-input" A reference to a filehandle, or the pathname of a file from wh +ich the invoking script's pod documentation should be read. It def +aults

    Or save the pod in a var

    my $script_pod = q{ ... }; open my($script_pod_fh), '<', \$script_pod; pod2usage( ... -input => $script_pod_fh );

      Perfect. Using the __DATA__ section didn't occur to me, and solves the problem.

      Thanks a lot!

      Steve
      --

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1015240]
Approved by davido
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (5)
As of 2014-12-28 12:59 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (181 votes), past polls