genhelp #1

=head1 NAME

genhelp - Build lib/VCP/Help.pm by extracting POD from the listed files

=head1 SYNOPSYS

    genhelp bin/vcp lib/VCP.pm lib/VCP/Foo.pm ...

=head1

When bundling libraries and POD files with PAR <= 0.79, it is difficult
to find and parse the files to generate help with.  So we extract it
and build it in to a Perl module as a bunch of strings using this tool.

See Makefile.PL for how this tool is automated.

=cut

###############################################################################
package My::Pod::Text;

use POD::Text;

@ISA = qw( Pod::Text );

sub output {
    shift->{OutputString} .= $_[0];
}

###############################################################################
package main;

use strict;
use List::Util;

use lib 'lib';

open OUTPUT, ">lib/VCP/Help.pm" or die "$!: lib/VCP/Help.pm";

warn "writing lib/VCP/Help.pm\n";

print OUTPUT <<PREAMBLE;
package VCP::Help;

\%topics = (
PREAMBLE

my @topics;
my %seen;
for ( @ARGV ) {
    my $topic = lc $_;
    $topic =~ s{.*\b(bin|VCP)[\\/]}{}i;
    $topic =~ s{\..*}{};
    $topic =~ s{[\\/]}{::}g;

    warn( "Already emitted topic $topic from $seen{$topic}\n" ), next
        if $seen{$topic};
    $seen{$topic} = $_;
    push @topics, $topic;

    my $text = do {
        my $p = My::Pod::Text->new( width => 72 );
        $p->parse_from_file( $_ );
        $p->{OutputString};
    };

    $text =~ s/^TOPIC/ TOPIC/mg;

    1 while chomp $text;

    print OUTPUT "#" x 72, "\n'$topic' => <<'TOPIC',\n$text\nTOPIC\n";
}

{
    @topics = sort @topics;

    ## Display 3 columns of topics
    push @topics, "" while @topics % 3;

    my $l = List::Util::max( map length, @topics );

    my $m = @topics / 3;

    my $text = join "",
        "vcp help topics:\n\n",
        map(
           sprintf(
              "    %-${l}s   %-${l}s   %s\n",
              @topics[ $_, $_+$m, $_+2*$m ]
           ),
           (0..$m - 1)
        );

    print OUTPUT "#" x 72, "\n'topics' => <<'TOPIC',\n$text\nTOPIC\n";
}

{
    print OUTPUT "#" x 72, "\n'' => <<'TOPIC',\n", <<TOPIC, "TOPIC\n";
vcp - Version Copy, a tool for copying versions file repositories

help topics (use "vcp help <topic>" to see):

   vcp            General help for the vcp command

   source::cvs    Extracting from a cvs repository
   source::p4     Extracting from a p4 repository
   source::vss    Extracting from a VSS repository
   dest::cvs      Inserting in to a cvs repository
   dest::p4       Inserting in to a p4 repository

   newlines       Newline, ^Z and NULL issues
   process        How vcp works

   license        Copyright and license information
   topics         All available topics

The PAGER environment variable specifies pager program to use for
these help topics.
TOPIC
}

print OUTPUT <<POSTAMBLE;
);

sub print {
    my \$topic = shift;

    \$topic = '' unless defined \$topic;

    warn( "unkown help topic: '\$topic'\n\n" ), \$topic = 'topics'
        unless \$topics{\$topic};

    CORE::print \$topics{\$topic};
}

1;
POSTAMBLE