#!/usr/bin/perl
# Time-stamp: "2005-08-19 01:42:43 ADT"   sburke@cpan.org
#  desc{  turn Perl-and-Pod into all Pod  }

=head1 NAME

impodulate -- turn Perl-and-POD into all POD

=head1 SYNOPSIS

  % cat Foo.pm
  
  use strict;
  package Foo;
  
  =head1 NAME

  Foo -- woozle
  
  =cut
  
  sub fooify {
    (rand() < .5) ? "Foo!" : "Bar!";
  }

  % impodulate Foo.pm > code_in_pod.pod
  % cat code_in_pod.pod

  =pod
  
   . use strict;
   . package Foo;
  
  =head1 NAME

  Foo -- woozle

   . sub fooify {
   .   (rand() < .5) ? "Foo!" : "Bar!";
   . }

  % perldoc code_in_pod.pod
  [...]

All the not-POD parts of C<Foo.pm> have been turned into POD
verbatim paragraphs in C<code_in_pod.pod>.

=head1 DESCRIPTION

This program is so you can look at Perl files, with the POD bits
formatted as POD, but the Perl bits formatted as Perl.

Michael Schwern said he liked the feature of MacPerl's Shuck that
allows you to see Perl files that way, and that gave me the idea
to write this program.

=head1 SWITCHES

C<-tI<number>> : Sets tab expansion to I<number> spaces.  Default is 8.

=head1 WARNING

POD generated by impodulate might be invalid.  Here's how to write
POD-and-code that is valid when fed thru impodulate:

Make sure your file starts with:

  =head1 NAME
  
  Stuff -- thingy
  
  =cut
  
  ... and then the usual stuff.

(Many POD formatters require the first POD section in a
file to be a "=head1 NAME".  If you manage this, then
just edit the output of impodulate, to move the "=head1 NAME"
to the top.)

And don't do this:

  =head1 Stuff
  
  This module does stuff:
  
  =over
  
  =cut
  
  ...code...
  
  =item Thing
  
  Thing with the stuff.
  
  =cut

When run, the stuff in "...code..." ends up being a paragraph
between "=over" and "=item", and that's unacceptable to many
POD processors.

=head1 SEE ALSO

L<perldoc|perldoc>, L<perlpod|perlpod>.

=head1 COPYRIGHT AND DISCLAIMER

Copyright (c) 2001 Sean M. Burke.  All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=head1 AUTHOR

Sean M. Burke, C<sburke@cpan.org>

=cut

use strict;
use Text::Tabs;
my $in_pod = 0;

if(@ARGV and $ARGV[0] =~ m/^-t(\d+)$/s) {
  $Text::Tabs::tabstop = $1;
  shift @ARGV;
}

print "=pod\n\n";

while(<>) {
  $_ = "\n" unless m/\S/;
  if($in_pod) {
    if(m/^=cut/s) {
      $in_pod = 0;
      if(m/^=cut\s*/s) {
        # typical contentless cut: just suppress it
        $_ = "\n";
      } else {
        # must be like "=cut and now the code...", so pass thru.
        print "Z<>"; # to nullify the =cut
      }
    }
     # otherwise pass thru
  } else {
    # Not in pod
    if(m/^=[a-zA-Z]/s) { # starting pod!
      print "\n"; # can't hurt
      $in_pod = 1;
       # and pass thru
    } else {
      $_ = expand($_);
      print ' . ';
    }
  }
  print $_;
  if(eof) { # end of each file
    print "\n\n\n";
    $in_pod = 0;
  }
}

__END__