perl-5.16.2/installhtml - toolchain/perl - Git at Google

 #!./perl -Ilib -w

 # This file should really be extracted from a .PL file

 use strict;
 use Config;		# for config options in the makefile
 use File::Spec;
 use Getopt::Long;	# for command-line parsing
 use Cwd;
 use Pod::Html 'anchorify';

 =head1 NAME

 installhtml - converts a collection of POD pages to HTML format.

 =head1 SYNOPSIS

     installhtml  [--help] [--podpath=<name>:...:<name>] [--podroot=<name>]
          [--htmldir=<name>] [--htmlroot=<name>]  [--norecurse] [--recurse]
          [--splithead=<name>,...,<name>]   [--splititem=<name>,...,<name>]
          [--ignore=<name>,...,<name>]  [--verbose]

 =head1 DESCRIPTION

 I<installhtml> converts a collection of POD pages to a corresponding
 collection of HTML pages.  This is primarily used to convert the pod
 pages found in the perl distribution.

 =head1 OPTIONS

 =over 4

 =item B<--help> help

 Displays the usage.

 =item B<--podroot> POD search path base directory

 The base directory to search for all .pod and .pm files to be converted.
 Default is current directory.

 =item B<--podpath> POD search path

 The list of directories to search for .pod and .pm files to be converted.
 Default is 'podroot/.'.

 =item B<--recurse> recurse on subdirectories

 Whether or not to convert all .pm and .pod files found in subdirectories
 too.  Default is to not recurse.

 =item B<--htmldir> HTML destination directory

 The base directory which all HTML files will be written to.  This should
 be a path relative to the filesystem, not the resulting URL.

 =item B<--htmlroot> URL base directory

 The base directory which all resulting HTML files will be visible at in
 a URL.  The default is '/'.

 =item B<--splithead> POD files to split on =head directive

 Comma-separated list of pod files to split by the =head directive.  The
 .pod suffix is optional. These files should have names specified
 relative to podroot.

 =item B<--splititem> POD files to split on =item directive

 Comma-separated list of all pod files to split by the =item directive.
 The .pod suffix is optional.  I<installhtml> does not do the actual
 split, rather it invokes I<splitpod> to do the dirty work.  As with
 --splithead, these files should have names specified relative to podroot.

 =item B<--splitpod> Directory containing the splitpod program

 The directory containing the splitpod program. The default is 'podroot/pod'.

 =item B<--ignore> files to be ignored

 Comma-separated of files that shouldn't be installed, given relative
 to podroot.

 =item B<--verbose> verbose output

 Self-explanatory.

 =back

 =head1 EXAMPLE

 The following command-line is an example of the one we use to convert
 perl documentation:

     ./installhtml --podpath=lib:ext:pod:vms   \
 			--podroot=/usr/src/perl     \
 			--htmldir=/perl/nmanual     \
 			--htmlroot=/perl/nmanual    \
 			--splithead=pod/perlipc     \
 			--splititem=pod/perlfunc    \
 			--recurse \
 			--verbose

 =head1 AUTHOR

 Chris Hall E<lt>hallc@cs.colorado.eduE<gt>

 =cut

 my $usage;

 $usage =<<END_OF_USAGE;
 Usage: $0 --help --podpath=<name>:...:<name> --podroot=<name>
          --htmldir=<name> --htmlroot=<name> --norecurse --recurse
          --splithead=<name>,...,<name> --splititem=<name>,...,<name>
          --ignore=<name>,...,<name> --verbose

     --help      - this message
     --podpath   - colon-separated list of directories containing .pod and
                   .pm files to be converted (. by default).
     --podroot   - filesystem base directory from which all relative paths in
                   podpath stem (default is .).
     --htmldir   - directory to store resulting html files in relative
                   to the filesystem (\$podroot/html by default).
     --htmlroot  - http-server base directory from which all relative paths
                   in podpath stem (default is /).
     --norecurse - don't recurse on those subdirectories listed in podpath.
                   (default behavior).
     --recurse   - recurse on those subdirectories listed in podpath
     --splithead - comma-separated list of .pod or .pm files to split.  will
                   split each file into several smaller files at every occurrence
                   of a pod =head[1-6] directive.
     --splititem - comma-separated list of .pod or .pm files to split using
                   splitpod.
     --splitpod  - directory where the program splitpod can be found
                   (\$podroot/pod by default).
     --ignore    - comma-separated list of files that shouldn't be installed.
     --verbose   - self-explanatory.

 END_OF_USAGE

 my (@podpath, $podroot, $htmldir, $htmlroot, $recurse, @splithead,
     @splititem, $splitpod, $verbose, $pod2html, @ignore);

 @podpath = ( "." );	# colon-separated list of directories containing .pod
 			# and .pm files to be converted.
 $podroot = ".";		# assume the pods we want are here
 $htmldir = "";		# nothing for now...
 $htmlroot = "/";	# default value
 $recurse = 0;		# default behavior
 @splithead = ();	# don't split any files by default
 @splititem = ();	# don't split any files by default
 $splitpod = "";		# nothing for now.

 $verbose = 0;		# whether or not to print debugging info

 $pod2html = "pod/pod2html";

 usage("") unless @ARGV;

 # Overcome shell's p1,..,p8 limitation.
 # See vms/descrip_mms.template -> descrip.mms for invocation.
 if ( $^O eq 'VMS' ) { @ARGV = split(/\s+/,$ARGV[0]); }

 use vars qw( %Options );

 # parse the command-line
 my $result = GetOptions( \%Options, qw(
 	help
 	podpath=s
 	podroot=s
 	htmldir=s
 	htmlroot=s
 	ignore=s
 	recurse!
 	splithead=s
 	splititem=s
 	splitpod=s
 	verbose
 ));
 usage("invalid parameters") unless $result;
 parse_command_line();


 # set these variables to appropriate values if the user didn't specify
 #  values for them.
 $htmldir = "$htmlroot/html" unless $htmldir;
 $splitpod = "$podroot/pod" unless $splitpod;


 # make sure that the destination directory exists
 (mkdir($htmldir, 0755) ||
 	die "$0: cannot make directory $htmldir: $!\n") if ! -d $htmldir;


 # the following array will eventually contain files that are to be
 # ignored in the conversion process.  these are files that have been
 # process by splititem or splithead and should not be converted as a
 # result.
 my @splitdirs;

 # split pods. It's important to do this before convert ANY pods because
 # it may affect some of the links
 @splitdirs = ();    # files in these directories won't get an index
 split_on_head($podroot, $htmldir, \@splitdirs, \@ignore, @splithead);
 split_on_item($podroot,           \@splitdirs, \@ignore, @splititem);


 # convert the pod pages found in @poddirs
 #warn "converting files\n" if $verbose;
 #warn "\@ignore\t= @ignore\n" if $verbose;
 foreach my $dir (@podpath) {
     installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore);
 }


 # now go through and create master indices for each pod we split
 foreach my $dir (@splititem) {
     print "creating index $htmldir/$dir.html\n" if $verbose;
     create_index("$htmldir/$dir.html", "$htmldir/$dir");
 }

 foreach my $dir (@splithead) {
     (my $pod = $dir) =~ s,^.*/,,;
     $dir .= ".pod" unless $dir =~ /(\.pod|\.pm)$/;
     # let pod2html create the file
     runpod2html($dir, 1);

     # now go through and truncate after the index
     $dir =~ /^(.*?)(\.pod|\.pm)?$/sm;
     my $file = "$htmldir/$1";
     print "creating index $file.html\n" if $verbose;

     # read in everything until what would have been the first =head
     # directive, patching the index as we go.
     open(H, "<$file.html") ||
 	die "$0: error opening $file.html for input: $!\n";
     $/ = "";
     my @data = ();
     while (<H>) {
 	last if /name="name"/i;
 	$_ =~ s{href="#(.*)">}{
 	    my $url = "$pod/$1.html" ;
 	    $url = Pod::Html::relativize_url( $url, "$file.html" )
 	    if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' );
 	    "href=\"$url\">" ;
 	}egi;
 	push @data, $_;
     }
     close(H);

     # now rewrite the file
     open(H, ">$file.html") ||
 	die "$0: error opening $file.html for output: $!\n";
     print H "@data", "\n";
     close(H);
 }

 ##############################################################################


 sub usage {
     warn "$0: @_\n" if @_;
     die $usage;
 }


 sub parse_command_line {
     usage() if defined $Options{help};
     $Options{help} = ""; 	    	    # make -w shut up

     # list of directories
     @podpath   = split(":", $Options{podpath}) if defined $Options{podpath};

     # lists of files
     @splithead = split(",", $Options{splithead}) if defined $Options{splithead};
     @splititem = split(",", $Options{splititem}) if defined $Options{splititem};

     $htmldir  = $Options{htmldir}	    if defined $Options{htmldir};
     $htmlroot = $Options{htmlroot}	    if defined $Options{htmlroot};
     $podroot  = $Options{podroot}	    if defined $Options{podroot};
     $splitpod = $Options{splitpod}	    if defined $Options{splitpod};

     $recurse  = $Options{recurse}	    if defined $Options{recurse};
     $verbose  = $Options{verbose}	    if defined $Options{verbose};

     @ignore = map "$podroot/$_", split(",", $Options{ignore}) if defined $Options{ignore};
 }


 sub create_index {
     my($html, $dir) = @_;
     (my $pod = $dir) =~ s,^.*/,,;

     # get the list of .html files in this directory
     opendir(DIR, $dir) ||
 	die "$0: error opening directory $dir for reading: $!\n";
     my @files = sort(grep(/\.html?$/, readdir(DIR)));
     closedir(DIR);

     open(HTML, ">$html") ||
 	die "$0: error opening $html for output: $!\n";

     # for each .html file in the directory, extract the index
     #	embedded in the file and throw it into the big index.
     print HTML "<DL COMPACT>\n";
     foreach my $file (@files) {

 	my $filedata = do {
 	    open(my $in, "<$dir/$file") ||
 		die "$0: error opening $dir/$file for input: $!\n";
 	    local $/ = undef;
 	    <$in>;
 	};

 	# pull out the NAME section
 	my($lcp1, $lcp2) =
 	    ($filedata =~
 		m#<h1 id="NAME">NAME</h1>\s*<p>\s*(\S+)\s+-\s+(\S.*?\S)</p>#);
 	defined $lcp1 or die "$0: can't find NAME section in $dir/$file\n";

 	my $url= "$pod/$file" ;
 	if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' ) {
 	    $url = Pod::Html::relativize_url( "$pod/$file", $html ) ;
 	}

 	print HTML qq(<DT><A HREF="$url">);
 	print HTML "$lcp1</A></DT><DD>$lcp2</DD>\n";
     }
     print HTML "</DL>\n";

     close(HTML);
 }


 sub split_on_head {
     my($podroot, $htmldir, $splitdirs, $ignore, @splithead) = @_;
     my($pod, $dirname, $filename);

     # split the files specified in @splithead on =head[1-6] pod directives
     print "splitting files by head.\n" if $verbose && $#splithead >= 0;
     foreach $pod (@splithead) {
 	# figure out the directory name and filename
 	$pod      =~ s,^([^/]*)$,/$1,;
 	$pod      =~ m,(.*)/(.*?)(\.pod)?$,;
 	$dirname  = $1;
 	$filename = "$2.pod";

 	# since we are splitting this file it shouldn't be converted.
 	push(@$ignore, "$podroot/$dirname/$filename");

 	# split the pod
 	splitpod("$podroot/$dirname/$filename", "$podroot/$dirname", $htmldir,
 	    $splitdirs);
     }
 }


 sub split_on_item {
     my($podroot, $splitdirs, $ignore, @splititem) = @_;
     my($pwd, $dirname, $filename);

     print "splitting files by item.\n" if $verbose && $#splititem >= 0;
     $pwd = getcwd();
     my $splitter = File::Spec->rel2abs("$splitpod/splitpod", $pwd);
     my $perl = File::Spec->rel2abs($^X, $pwd);
     foreach my $pod (@splititem) {
 	# figure out the directory to split into
 	$pod      =~ s,^([^/]*)$,/$1,;
 	$pod      =~ m,(.*)/(.*?)(\.pod)?$,;
 	$dirname  = "$1/$2";
 	$filename = "$2.pod";

 	# since we are splitting this file it shouldn't be converted.
 	push(@$ignore, "$podroot/$dirname.pod");

 	# split the pod
 	push(@$splitdirs, "$podroot/$dirname");
 	if (! -d "$podroot/$dirname") {
 	    mkdir("$podroot/$dirname", 0755) ||
 		    die "$0: error creating directory $podroot/$dirname: $!\n";
 	}
 	chdir("$podroot/$dirname") ||
 	    die "$0: error changing to directory $podroot/$dirname: $!\n";
 	die "$splitter not found. Use '-splitpod dir' option.\n"
 	    unless -f $splitter;
 	system($perl, $splitter, "../$filename") &&
 	    warn "$0: error running '$splitter ../$filename'"
 		 ." from $podroot/$dirname";
     }
     chdir($pwd);
 }


 #
 # splitpod - splits a .pod file into several smaller .pod files
 #  where a new file is started each time a =head[1-6] pod directive
 #  is encountered in the input file.
 #
 sub splitpod {
     my($pod, $poddir, $htmldir, $splitdirs) = @_;
     my(@poddata, @filedata, @heads);
     my($file, $i, $j, $prevsec, $section, $nextsec);

     print "splitting $pod\n" if $verbose;

     # read the file in paragraphs
     $/ = "";
     open(SPLITIN, "<$pod") ||
 	die "$0: error opening $pod for input: $!\n";
     @filedata = <SPLITIN>;
     close(SPLITIN) ||
 	die "$0: error closing $pod: $!\n";

     # restore the file internally by =head[1-6] sections
     @poddata = ();
     for ($i = 0, $j = -1; $i <= $#filedata; $i++) {
 	$j++ if ($filedata[$i] =~ /^\s*=head[1-6]/);
 	if ($j >= 0) {
 	    $poddata[$j]  = "" unless defined $poddata[$j];
 	    $poddata[$j] .= "\n$filedata[$i]" if $j >= 0;
 	}
     }

     # create list of =head[1-6] sections so that we can rewrite
     #  L<> links as necessary.
     my %heads = ();
     foreach $i (0..$#poddata) {
 	$heads{anchorify($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/;
     }

     # create a directory of a similar name and store all the
     #  files in there
     $pod =~ s,.*/(.*),$1,;	# get the last part of the name
     my $dir = $pod;
     $dir =~ s/\.pod//g;
     push(@$splitdirs, "$poddir/$dir");
     mkdir("$poddir/$dir", 0755) ||
 	die "$0: could not create directory $poddir/$dir: $!\n"
 	unless -d "$poddir/$dir";

     $poddata[0] =~ /^\s*=head[1-6]\s+(.*)/;
     $section    = "";
     $nextsec    = $1;

     # for each section of the file create a separate pod file
     for ($i = 0; $i <= $#poddata; $i++) {
 	# determine the "prev" and "next" links
 	$prevsec = $section;
 	$section = $nextsec;
 	if ($i < $#poddata) {
 	    $poddata[$i+1] =~ /^\s*=head[1-6]\s+(.*)/;
 	    $nextsec       = $1;
 	} else {
 	    $nextsec = "";
 	}

 	# determine an appropriate filename (this must correspond with
 	#  what pod2html will try and guess)
 	# $poddata[$i] =~ /^\s*=head[1-6]\s+(.*)/;
 	$file = "$dir/" . anchorify($section) . ".pod";

 	# create the new .pod file
 	print "\tcreating $poddir/$file\n" if $verbose;
 	open(SPLITOUT, ">$poddir/$file") ||
 	    die "$0: error opening $poddir/$file for output: $!\n";
 	$poddata[$i] =~ s,L<([^<>]*)>,
 			defined $heads{anchorify($1)} ? "L<$dir/$1>" : "L<$1>"
 		     ,ge;
 	print SPLITOUT $poddata[$i]."\n\n";
 	print SPLITOUT "=over 4\n\n";
 	print SPLITOUT "=item *\n\nBack to L<$dir/\"$prevsec\">\n\n" if $prevsec;
 	print SPLITOUT "=item *\n\nForward to L<$dir/\"$nextsec\">\n\n" if $nextsec;
 	print SPLITOUT "=item *\n\nUp to L<$dir>\n\n";
 	print SPLITOUT "=back\n\n";
 	close(SPLITOUT) ||
 	    die "$0: error closing $poddir/$file: $!\n";
     }
 }


 #
 # installdir - takes care of converting the .pod and .pm files in the
 #  current directory to .html files and then installing those.
 #
 sub installdir {
     my($dir, $recurse, $podroot, $splitdirs, $ignore) = @_;
     my(@dirlist, @podlist, @pmlist, $doindex);

     @dirlist = ();	# directories to recurse on
     @podlist = ();	# .pod files to install
     @pmlist  = ();	# .pm files to install

     # should files in this directory get an index?
     $doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1);

     opendir(DIR, "$podroot/$dir")
 	|| die "$0: error opening directory $podroot/$dir: $!\n";

     # find the directories to recurse on
     @dirlist = map { if ($^O eq 'VMS') {/^(.*)\.dir$/i; "$dir/$1";} else {"$dir/$_";}}
 	grep(-d "$podroot/$dir/$_" && !/^\.{1,2}/, readdir(DIR)) if $recurse;
     rewinddir(DIR);

     # find all the .pod files within the directory
     @podlist = map { /^(.*)\.pod$/; "$dir/$1" }
 	grep(! -d "$podroot/$dir/$_" && /\.pod$/, readdir(DIR));
     rewinddir(DIR);

     # find all the .pm files within the directory
     @pmlist = map { /^(.*)\.pm$/; "$dir/$1" }
 	grep(! -d "$podroot/$dir/$_" && /\.pm$/, readdir(DIR));

     closedir(DIR);

     # recurse on all subdirectories we kept track of
     foreach $dir (@dirlist) {
 	installdir($dir, $recurse, $podroot, $splitdirs, $ignore);
     }

     # install all the pods we found
     foreach my $pod (@podlist) {
 	# check if we should ignore it.
 	next if $pod =~ m(/t/); # comes from a test file
 	next if grep($_ eq "$pod.pod", @$ignore);

 	# check if a .pm files exists too
 	if (grep($_ eq $pod, @pmlist)) {
 	    print  "$0: Warning both '$podroot/$pod.pod' and "
 		. "'$podroot/$pod.pm' exist, using pod\n";
 	    push(@ignore, "$pod.pm");
 	}
 	runpod2html("$pod.pod", $doindex);
     }

     # install all the .pm files we found
     foreach my $pm (@pmlist) {
 	# check if we should ignore it.
 	next if $pm =~ m(/t/); # comes from a test file
 	next if grep($_ eq "$pm.pm", @ignore);

 	runpod2html("$pm.pm", $doindex);
     }
 }


 #
 # runpod2html - invokes pod2html to convert a .pod or .pm file to a .html
 #  file.
 #
 sub runpod2html {
     my($pod, $doindex) = @_;
     my($html, $i, $dir, @dirs);

     $html = $pod;
     $html =~ s/\.(pod|pm)$/.html/g;

     # make sure the destination directories exist
     @dirs = split("/", $html);
     $dir  = "$htmldir/";
     for ($i = 0; $i < $#dirs; $i++) {
 	if (! -d "$dir$dirs[$i]") {
 	    mkdir("$dir$dirs[$i]", 0755) ||
 		die "$0: error creating directory $dir$dirs[$i]: $!\n";
 	}
 	$dir .= "$dirs[$i]/";
     }

     # invoke pod2html
     print "$podroot/$pod => $htmldir/$html\n" if $verbose;
     Pod::Html::pod2html(
         "--htmldir=$htmldir",
 	"--htmlroot=$htmlroot",
 	"--podpath=".join(":", @podpath),
 	"--podroot=$podroot",
 	"--header",
 	($doindex ? "--index" : "--noindex"),
 	"--" . ($recurse ? "" : "no") . "recurse",
 	"--infile=$podroot/$pod", "--outfile=$htmldir/$html");
     die "$0: error running $pod2html: $!\n" if $?;
 }
	#!./perl -Ilib -w

	# This file should really be extracted from a .PL file

	use strict;
	use Config; # for config options in the makefile
	use File::Spec;
	use Getopt::Long; # for command-line parsing
	use Cwd;
	use Pod::Html 'anchorify';

	=head1 NAME

	installhtml - converts a collection of POD pages to HTML format.

	=head1 SYNOPSIS

	installhtml [--help] [--podpath=<name>:...:<name>] [--podroot=<name>]
	[--htmldir=<name>] [--htmlroot=<name>] [--norecurse] [--recurse]
	[--splithead=<name>,...,<name>] [--splititem=<name>,...,<name>]
	[--ignore=<name>,...,<name>] [--verbose]

	=head1 DESCRIPTION

	I<installhtml> converts a collection of POD pages to a corresponding
	collection of HTML pages. This is primarily used to convert the pod
	pages found in the perl distribution.

	=head1 OPTIONS

	=over 4

	=item B<--help> help

	Displays the usage.

	=item B<--podroot> POD search path base directory

	The base directory to search for all .pod and .pm files to be converted.
	Default is current directory.

	=item B<--podpath> POD search path

	The list of directories to search for .pod and .pm files to be converted.
	Default is 'podroot/.'.

	=item B<--recurse> recurse on subdirectories

	Whether or not to convert all .pm and .pod files found in subdirectories
	too. Default is to not recurse.

	=item B<--htmldir> HTML destination directory

	The base directory which all HTML files will be written to. This should
	be a path relative to the filesystem, not the resulting URL.

	=item B<--htmlroot> URL base directory

	The base directory which all resulting HTML files will be visible at in
	a URL. The default is '/'.

	=item B<--splithead> POD files to split on =head directive

	Comma-separated list of pod files to split by the =head directive. The
	.pod suffix is optional. These files should have names specified
	relative to podroot.

	=item B<--splititem> POD files to split on =item directive

	Comma-separated list of all pod files to split by the =item directive.
	The .pod suffix is optional. I<installhtml> does not do the actual
	split, rather it invokes I<splitpod> to do the dirty work. As with
	--splithead, these files should have names specified relative to podroot.

	=item B<--splitpod> Directory containing the splitpod program

	The directory containing the splitpod program. The default is 'podroot/pod'.

	=item B<--ignore> files to be ignored

	Comma-separated of files that shouldn't be installed, given relative
	to podroot.

	=item B<--verbose> verbose output

	Self-explanatory.

	=back

	=head1 EXAMPLE

	The following command-line is an example of the one we use to convert
	perl documentation:

	./installhtml --podpath=lib:ext:pod:vms \
	--podroot=/usr/src/perl \
	--htmldir=/perl/nmanual \
	--htmlroot=/perl/nmanual \
	--splithead=pod/perlipc \
	--splititem=pod/perlfunc \
	--recurse \
	--verbose

	=head1 AUTHOR

	Chris Hall E<lt>hallc@cs.colorado.eduE<gt>

	=cut

	my $usage;

	$usage =<<END_OF_USAGE;
	Usage: $0 --help --podpath=<name>:...:<name> --podroot=<name>
	--htmldir=<name> --htmlroot=<name> --norecurse --recurse
	--splithead=<name>,...,<name> --splititem=<name>,...,<name>
	--ignore=<name>,...,<name> --verbose

	--help - this message
	--podpath - colon-separated list of directories containing .pod and
	.pm files to be converted (. by default).
	--podroot - filesystem base directory from which all relative paths in
	podpath stem (default is .).
	--htmldir - directory to store resulting html files in relative
	to the filesystem (\$podroot/html by default).
	--htmlroot - http-server base directory from which all relative paths
	in podpath stem (default is /).
	--norecurse - don't recurse on those subdirectories listed in podpath.
	(default behavior).
	--recurse - recurse on those subdirectories listed in podpath
	--splithead - comma-separated list of .pod or .pm files to split. will
	split each file into several smaller files at every occurrence
	of a pod =head[1-6] directive.
	--splititem - comma-separated list of .pod or .pm files to split using
	splitpod.
	--splitpod - directory where the program splitpod can be found
	(\$podroot/pod by default).
	--ignore - comma-separated list of files that shouldn't be installed.
	--verbose - self-explanatory.

	END_OF_USAGE

	my (@podpath, $podroot, $htmldir, $htmlroot, $recurse, @splithead,
	@splititem, $splitpod, $verbose, $pod2html, @ignore);

	@podpath = ( "." ); # colon-separated list of directories containing .pod
	# and .pm files to be converted.
	$podroot = "."; # assume the pods we want are here
	$htmldir = ""; # nothing for now...
	$htmlroot = "/"; # default value
	$recurse = 0; # default behavior
	@splithead = (); # don't split any files by default
	@splititem = (); # don't split any files by default
	$splitpod = ""; # nothing for now.

	$verbose = 0; # whether or not to print debugging info

	$pod2html = "pod/pod2html";

	usage("") unless @ARGV;

	# Overcome shell's p1,..,p8 limitation.
	# See vms/descrip_mms.template -> descrip.mms for invocation.
	if ( $^O eq 'VMS' ) { @ARGV = split(/\s+/,$ARGV[0]); }

	use vars qw( %Options );

	# parse the command-line
	my $result = GetOptions( \%Options, qw(
	help
	podpath=s
	podroot=s
	htmldir=s
	htmlroot=s
	ignore=s
	recurse!
	splithead=s
	splititem=s
	splitpod=s
	verbose
	));
	usage("invalid parameters") unless $result;
	parse_command_line();


	# set these variables to appropriate values if the user didn't specify
	# values for them.
	$htmldir = "$htmlroot/html" unless $htmldir;
	$splitpod = "$podroot/pod" unless $splitpod;


	# make sure that the destination directory exists
	(mkdir($htmldir, 0755) \|\|
	die "$0: cannot make directory $htmldir: $!\n") if ! -d $htmldir;


	# the following array will eventually contain files that are to be
	# ignored in the conversion process. these are files that have been
	# process by splititem or splithead and should not be converted as a
	# result.
	my @splitdirs;

	# split pods. It's important to do this before convert ANY pods because
	# it may affect some of the links
	@splitdirs = (); # files in these directories won't get an index
	split_on_head($podroot, $htmldir, \@splitdirs, \@ignore, @splithead);
	split_on_item($podroot, \@splitdirs, \@ignore, @splititem);


	# convert the pod pages found in @poddirs
	#warn "converting files\n" if $verbose;
	#warn "\@ignore\t= @ignore\n" if $verbose;
	foreach my $dir (@podpath) {
	installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore);
	}


	# now go through and create master indices for each pod we split
	foreach my $dir (@splititem) {
	print "creating index $htmldir/$dir.html\n" if $verbose;
	create_index("$htmldir/$dir.html", "$htmldir/$dir");
	}

	foreach my $dir (@splithead) {
	(my $pod = $dir) =~ s,^.*/,,;
	$dir .= ".pod" unless $dir =~ /(\.pod\|\.pm)$/;
	# let pod2html create the file
	runpod2html($dir, 1);

	# now go through and truncate after the index
	$dir =~ /^(.*?)(\.pod\|\.pm)?$/sm;
	my $file = "$htmldir/$1";
	print "creating index $file.html\n" if $verbose;

	# read in everything until what would have been the first =head
	# directive, patching the index as we go.
	open(H, "<$file.html") \|\|
	die "$0: error opening $file.html for input: $!\n";
	$/ = "";
	my @data = ();
	while (<H>) {
	last if /name="name"/i;
	$_ =~ s{href="#(.*)">}{
	my $url = "$pod/$1.html" ;
	$url = Pod::Html::relativize_url( $url, "$file.html" )
	if ( ! defined $Options{htmlroot} \|\| $Options{htmlroot} eq '' );
	"href=\"$url\">" ;
	}egi;
	push @data, $_;
	}
	close(H);

	# now rewrite the file
	open(H, ">$file.html") \|\|
	die "$0: error opening $file.html for output: $!\n";
	print H "@data", "\n";
	close(H);
	}

	##############################################################################


	sub usage {
	warn "$0: @_\n" if @_;
	die $usage;
	}


	sub parse_command_line {
	usage() if defined $Options{help};
	$Options{help} = ""; # make -w shut up

	# list of directories
	@podpath = split(":", $Options{podpath}) if defined $Options{podpath};

	# lists of files
	@splithead = split(",", $Options{splithead}) if defined $Options{splithead};
	@splititem = split(",", $Options{splititem}) if defined $Options{splititem};

	$htmldir = $Options{htmldir} if defined $Options{htmldir};
	$htmlroot = $Options{htmlroot} if defined $Options{htmlroot};
	$podroot = $Options{podroot} if defined $Options{podroot};
	$splitpod = $Options{splitpod} if defined $Options{splitpod};

	$recurse = $Options{recurse} if defined $Options{recurse};
	$verbose = $Options{verbose} if defined $Options{verbose};

	@ignore = map "$podroot/$_", split(",", $Options{ignore}) if defined $Options{ignore};
	}


	sub create_index {
	my($html, $dir) = @_;
	(my $pod = $dir) =~ s,^.*/,,;

	# get the list of .html files in this directory
	opendir(DIR, $dir) \|\|
	die "$0: error opening directory $dir for reading: $!\n";
	my @files = sort(grep(/\.html?$/, readdir(DIR)));
	closedir(DIR);

	open(HTML, ">$html") \|\|
	die "$0: error opening $html for output: $!\n";

	# for each .html file in the directory, extract the index
	# embedded in the file and throw it into the big index.
	print HTML "<DL COMPACT>\n";
	foreach my $file (@files) {

	my $filedata = do {
	open(my $in, "<$dir/$file") \|\|
	die "$0: error opening $dir/$file for input: $!\n";
	local $/ = undef;
	<$in>;
	};

	# pull out the NAME section
	my($lcp1, $lcp2) =
	($filedata =~
	m#<h1 id="NAME">NAME</h1>\s<p>\s(\S+)\s+-\s+(\S.*?\S)</p>#);
	defined $lcp1 or die "$0: can't find NAME section in $dir/$file\n";

	my $url= "$pod/$file" ;
	if ( ! defined $Options{htmlroot} \|\| $Options{htmlroot} eq '' ) {
	$url = Pod::Html::relativize_url( "$pod/$file", $html ) ;
	}

	print HTML qq(<DT><A HREF="$url">);
	print HTML "$lcp1</A></DT><DD>$lcp2</DD>\n";
	}
	print HTML "</DL>\n";

	close(HTML);
	}


	sub split_on_head {
	my($podroot, $htmldir, $splitdirs, $ignore, @splithead) = @_;
	my($pod, $dirname, $filename);

	# split the files specified in @splithead on =head[1-6] pod directives
	print "splitting files by head.\n" if $verbose && $#splithead >= 0;
	foreach $pod (@splithead) {
	# figure out the directory name and filename
	$pod =~ s,^([^/]*)$,/$1,;
	$pod =~ m,(.)/(.?)(\.pod)?$,;
	$dirname = $1;
	$filename = "$2.pod";

	# since we are splitting this file it shouldn't be converted.
	push(@$ignore, "$podroot/$dirname/$filename");

	# split the pod
	splitpod("$podroot/$dirname/$filename", "$podroot/$dirname", $htmldir,
	$splitdirs);
	}
	}


	sub split_on_item {
	my($podroot, $splitdirs, $ignore, @splititem) = @_;
	my($pwd, $dirname, $filename);

	print "splitting files by item.\n" if $verbose && $#splititem >= 0;
	$pwd = getcwd();
	my $splitter = File::Spec->rel2abs("$splitpod/splitpod", $pwd);
	my $perl = File::Spec->rel2abs($^X, $pwd);
	foreach my $pod (@splititem) {
	# figure out the directory to split into
	$pod =~ s,^([^/]*)$,/$1,;
	$pod =~ m,(.)/(.?)(\.pod)?$,;
	$dirname = "$1/$2";
	$filename = "$2.pod";

	# since we are splitting this file it shouldn't be converted.
	push(@$ignore, "$podroot/$dirname.pod");

	# split the pod
	push(@$splitdirs, "$podroot/$dirname");
	if (! -d "$podroot/$dirname") {
	mkdir("$podroot/$dirname", 0755) \|\|
	die "$0: error creating directory $podroot/$dirname: $!\n";
	}
	chdir("$podroot/$dirname") \|\|
	die "$0: error changing to directory $podroot/$dirname: $!\n";
	die "$splitter not found. Use '-splitpod dir' option.\n"
	unless -f $splitter;
	system($perl, $splitter, "../$filename") &&
	warn "$0: error running '$splitter ../$filename'"
	." from $podroot/$dirname";
	}
	chdir($pwd);
	}


	#
	# splitpod - splits a .pod file into several smaller .pod files
	# where a new file is started each time a =head[1-6] pod directive
	# is encountered in the input file.
	#
	sub splitpod {
	my($pod, $poddir, $htmldir, $splitdirs) = @_;
	my(@poddata, @filedata, @heads);
	my($file, $i, $j, $prevsec, $section, $nextsec);

	print "splitting $pod\n" if $verbose;

	# read the file in paragraphs
	$/ = "";
	open(SPLITIN, "<$pod") \|\|
	die "$0: error opening $pod for input: $!\n";
	@filedata = <SPLITIN>;
	close(SPLITIN) \|\|
	die "$0: error closing $pod: $!\n";

	# restore the file internally by =head[1-6] sections
	@poddata = ();
	for ($i = 0, $j = -1; $i <= $#filedata; $i++) {
	$j++ if ($filedata[$i] =~ /^\s*=head[1-6]/);
	if ($j >= 0) {
	$poddata[$j] = "" unless defined $poddata[$j];
	$poddata[$j] .= "\n$filedata[$i]" if $j >= 0;
	}
	}

	# create list of =head[1-6] sections so that we can rewrite
	# L<> links as necessary.
	my %heads = ();
	foreach $i (0..$#poddata) {
	$heads{anchorify($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/;
	}

	# create a directory of a similar name and store all the
	# files in there
	$pod =~ s,./(.),$1,; # get the last part of the name
	my $dir = $pod;
	$dir =~ s/\.pod//g;
	push(@$splitdirs, "$poddir/$dir");
	mkdir("$poddir/$dir", 0755) \|\|
	die "$0: could not create directory $poddir/$dir: $!\n"
	unless -d "$poddir/$dir";

	$poddata[0] =~ /^\s=head[1-6]\s+(.)/;
	$section = "";
	$nextsec = $1;

	# for each section of the file create a separate pod file
	for ($i = 0; $i <= $#poddata; $i++) {
	# determine the "prev" and "next" links
	$prevsec = $section;
	$section = $nextsec;
	if ($i < $#poddata) {
	$poddata[$i+1] =~ /^\s=head[1-6]\s+(.)/;
	$nextsec = $1;
	} else {
	$nextsec = "";
	}

	# determine an appropriate filename (this must correspond with
	# what pod2html will try and guess)
	# $poddata[$i] =~ /^\s=head[1-6]\s+(.)/;
	$file = "$dir/" . anchorify($section) . ".pod";

	# create the new .pod file
	print "\tcreating $poddir/$file\n" if $verbose;
	open(SPLITOUT, ">$poddir/$file") \|\|
	die "$0: error opening $poddir/$file for output: $!\n";
	$poddata[$i] =~ s,L<([^<>]*)>,
	defined $heads{anchorify($1)} ? "L<$dir/$1>" : "L<$1>"
	,ge;
	print SPLITOUT $poddata[$i]."\n\n";
	print SPLITOUT "=over 4\n\n";
	print SPLITOUT "=item *\n\nBack to L<$dir/\"$prevsec\">\n\n" if $prevsec;
	print SPLITOUT "=item *\n\nForward to L<$dir/\"$nextsec\">\n\n" if $nextsec;
	print SPLITOUT "=item *\n\nUp to L<$dir>\n\n";
	print SPLITOUT "=back\n\n";
	close(SPLITOUT) \|\|
	die "$0: error closing $poddir/$file: $!\n";
	}
	}


	#
	# installdir - takes care of converting the .pod and .pm files in the
	# current directory to .html files and then installing those.
	#
	sub installdir {
	my($dir, $recurse, $podroot, $splitdirs, $ignore) = @_;
	my(@dirlist, @podlist, @pmlist, $doindex);

	@dirlist = (); # directories to recurse on
	@podlist = (); # .pod files to install
	@pmlist = (); # .pm files to install

	# should files in this directory get an index?
	$doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1);

	opendir(DIR, "$podroot/$dir")
	\|\| die "$0: error opening directory $podroot/$dir: $!\n";

	# find the directories to recurse on
	@dirlist = map { if ($^O eq 'VMS') {/^(.*)\.dir$/i; "$dir/$1";} else {"$dir/$_";}}
	grep(-d "$podroot/$dir/$_" && !/^\.{1,2}/, readdir(DIR)) if $recurse;
	rewinddir(DIR);

	# find all the .pod files within the directory
	@podlist = map { /^(.*)\.pod$/; "$dir/$1" }
	grep(! -d "$podroot/$dir/$_" && /\.pod$/, readdir(DIR));
	rewinddir(DIR);

	# find all the .pm files within the directory
	@pmlist = map { /^(.*)\.pm$/; "$dir/$1" }
	grep(! -d "$podroot/$dir/$_" && /\.pm$/, readdir(DIR));

	closedir(DIR);

	# recurse on all subdirectories we kept track of
	foreach $dir (@dirlist) {
	installdir($dir, $recurse, $podroot, $splitdirs, $ignore);
	}

	# install all the pods we found
	foreach my $pod (@podlist) {
	# check if we should ignore it.
	next if $pod =~ m(/t/); # comes from a test file
	next if grep($_ eq "$pod.pod", @$ignore);

	# check if a .pm files exists too
	if (grep($_ eq $pod, @pmlist)) {
	print "$0: Warning both '$podroot/$pod.pod' and "
	. "'$podroot/$pod.pm' exist, using pod\n";
	push(@ignore, "$pod.pm");
	}
	runpod2html("$pod.pod", $doindex);
	}

	# install all the .pm files we found
	foreach my $pm (@pmlist) {
	# check if we should ignore it.
	next if $pm =~ m(/t/); # comes from a test file
	next if grep($_ eq "$pm.pm", @ignore);

	runpod2html("$pm.pm", $doindex);
	}
	}


	#
	# runpod2html - invokes pod2html to convert a .pod or .pm file to a .html
	# file.
	#
	sub runpod2html {
	my($pod, $doindex) = @_;
	my($html, $i, $dir, @dirs);

	$html = $pod;
	$html =~ s/\.(pod\|pm)$/.html/g;

	# make sure the destination directories exist
	@dirs = split("/", $html);
	$dir = "$htmldir/";
	for ($i = 0; $i < $#dirs; $i++) {
	if (! -d "$dir$dirs[$i]") {
	mkdir("$dir$dirs[$i]", 0755) \|\|
	die "$0: error creating directory $dir$dirs[$i]: $!\n";
	}
	$dir .= "$dirs[$i]/";
	}

	# invoke pod2html
	print "$podroot/$pod => $htmldir/$html\n" if $verbose;
	Pod::Html::pod2html(
	"--htmldir=$htmldir",
	"--htmlroot=$htmlroot",
	"--podpath=".join(":", @podpath),
	"--podroot=$podroot",
	"--header",
	($doindex ? "--index" : "--noindex"),
	"--" . ($recurse ? "" : "no") . "recurse",
	"--infile=$podroot/$pod", "--outfile=$htmldir/$html");
	die "$0: error running $pod2html: $!\n" if $?;
	}