[p5sagit/p5-mst-13.2.git] / installhtml

#!./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>]
	 [--libpods=<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<--libpods> library PODs for LE<lt>E<gt> links

Comma-separated list of "library" pod files.  This is the same list that
will be passed to pod2html when any pod is converted.

=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    \
			--libpods=perlfunc,perlguts,perlvar,perlrun,perlop \
			--recurse \
			--verbose

=head1 AUTHOR

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

=head1 TODO

=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>
	 --libpods=<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 /).
    --libpods   - comma-separated list of files to search for =item pod
                  directives in as targets of C<> and implicit links (empty
                  by default).
    --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).
    --verbose   - self-explanatory.

END_OF_USAGE

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

@libpods = ();
@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 invokation.
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
	libpods=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 @ignore = ();
my @splitdirs;

# split pods.  its important to do this before convert ANY pods because
#  it may effect 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};
    @libpods   = split(",", $Options{libpods}) if defined $Options{libpods};

    $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};
}


sub create_index {
    my($html, $dir) = @_;
    (my $pod = $dir) =~ s,^.*/,,;
    my(@files, @filedata, @index, $file);
    my($lcp1,$lcp2);


    # get the list of .html files in this directory
    opendir(DIR, $dir) ||
	die "$0: error opening directory $dir for reading: $!\n";
    @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 $file (@files) {
	$/ = "";

	open(IN, "<$dir/$file") ||
	    die "$0: error opening $dir/$file for input: $!\n";
	@filedata = <IN>;
	close(IN);

	# pull out the NAME section
	my $name;
	($name) = grep(/name="name"/i, @filedata);
	($lcp1,$lcp2) = ($name =~ m,/H1>\s(\S+)\s[\s-]*(.*?)\s*$,smi);
	if (defined $lcp1 and $lcp1 =~ m,^<P>$,i) { # Uninteresting.  Try again.
	    ($lcp1,$lcp2) = ($name =~ m,/H1>\s<P>\s*(\S+)\s[\s-]*(.*?)\s*$,smi);
	}
	my $url= "$pod/$file" ;
	if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' ) {
	    $url = Pod::Html::relativize_url( "$pod/$file", $html ) ;
	}

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

	next;

	@index = grep(/<!-- INDEX BEGIN -->.*<!-- INDEX END -->/s,
		    @filedata);
	for (@index) {
	    s/<!-- INDEX BEGIN -->(\s*<!--)(.*)(-->\s*)<!-- INDEX END -->/$lcp2/s;
	    s,#,$dir/$file#,g;
	    print HTML "$_\n<P><HR><P>\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 grep($_ eq "$podroot/$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 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", "--netscape",
	"--header",
	($doindex ? "--index" : "--noindex"),
	"--" . ($recurse ? "" : "no") . "recurse",
	($#libpods >= 0) ? "--libpods=" . join(":", @libpods) : "",
	"--infile=$podroot/$pod", "--outfile=$htmldir/$html");
    die "$0: error running $pod2html: $!\n" if $?;
}
Commit	Line	Data
3d8876fc	1	#!./perl -Ilib -w
90248788	2
53542a37	3	# This file should really be extracted from a .PL file
54310121	4
3d8876fc	5	use strict;
54310121	6	use Config; # for config options in the makefile
cac3fadd	7	use File::Spec;
54310121	8	use Getopt::Long; # for command-line parsing
54310121	9	use Cwd;
776d31fe	10	use Pod::Html 'anchorify';
54310121	11
54310121	12	=head1 NAME
	13
	14	installhtml - converts a collection of POD pages to HTML format.
	15
	16	=head1 SYNOPSIS
	17
	18	installhtml [--help] [--podpath=<name>:...:<name>] [--podroot=<name>]
	19	[--htmldir=<name>] [--htmlroot=<name>] [--norecurse] [--recurse]
	20	[--splithead=<name>,...,<name>] [--splititem=<name>,...,<name>]
	21	[--libpods=<name>,...,<name>] [--verbose]
	22
	23	=head1 DESCRIPTION
	24
	25	I<installhtml> converts a collection of POD pages to a corresponding
	26	collection of HTML pages. This is primarily used to convert the pod
	27	pages found in the perl distribution.
	28
	29	=head1 OPTIONS
	30
	31	=over 4
	32
	33	=item B<--help> help
	34
	35	Displays the usage.
	36
3e3baf6d	37	=item B<--podroot> POD search path base directory
	38
	39	The base directory to search for all .pod and .pm files to be converted.
	40	Default is current directory.
	41
54310121	42	=item B<--podpath> POD search path
54310121	43
e05c04ea	44	The list of directories to search for .pod and .pm files to be converted.
54310121	45	Default is `podroot/.'.
54310121	46
3e3baf6d	47	=item B<--recurse> recurse on subdirectories
54310121	48
3e3baf6d	49	Whether or not to convert all .pm and .pod files found in subdirectories
3e3baf6d	50	too. Default is to not recurse.
54310121	51
	52	=item B<--htmldir> HTML destination directory
	53
	54	The base directory which all HTML files will be written to. This should
	55	be a path relative to the filesystem, not the resulting URL.
	56
	57	=item B<--htmlroot> URL base directory
	58
	59	The base directory which all resulting HTML files will be visible at in
	60	a URL. The default is `/'.
	61
54310121	62	=item B<--splithead> POD files to split on =head directive
54310121	63
af19f77d	64	Comma-separated list of pod files to split by the =head directive. The
3e3baf6d	65	.pod suffix is optional. These files should have names specified
3e3baf6d	66	relative to podroot.
54310121	67
	68	=item B<--splititem> POD files to split on =item directive
	69
af19f77d	70	Comma-separated list of all pod files to split by the =item directive.
3e3baf6d	71	The .pod suffix is optional. I<installhtml> does not do the actual
	72	split, rather it invokes I<splitpod> to do the dirty work. As with
	73	--splithead, these files should have names specified relative to podroot.
	74
	75	=item B<--splitpod> Directory containing the splitpod program
	76
	77	The directory containing the splitpod program. The default is `podroot/pod'.
54310121	78
	79	=item B<--libpods> library PODs for LE<lt>E<gt> links
	80
af19f77d	81	Comma-separated list of "library" pod files. This is the same list that
54310121	82	will be passed to pod2html when any pod is converted.
	83
	84	=item B<--verbose> verbose output
	85
	86	Self-explanatory.
	87
	88	=back
	89
	90	=head1 EXAMPLE
	91
	92	The following command-line is an example of the one we use to convert
	93	perl documentation:
	94
	95	./installhtml --podpath=lib:ext:pod:vms \
84902520	96	--podroot=/usr/src/perl \
	97	--htmldir=/perl/nmanual \
	98	--htmlroot=/perl/nmanual \
	99	--splithead=pod/perlipc \
	100	--splititem=pod/perlfunc \
af19f77d	101	--libpods=perlfunc,perlguts,perlvar,perlrun,perlop \
84902520	102	--recurse \
84902520	103	--verbose
54310121	104
	105	=head1 AUTHOR
	106
	107	Chris Hall E<lt>hallc@cs.colorado.eduE<gt>
	108
	109	=head1 TODO
	110
	111	=cut
	112
3d8876fc	113	my $usage;
3d8876fc	114
54310121	115	$usage =<<END_OF_USAGE;
	116	Usage: $0 --help --podpath=<name>:...:<name> --podroot=<name>
	117	--htmldir=<name> --htmlroot=<name> --norecurse --recurse
	118	--splithead=<name>,...,<name> --splititem=<name>,...,<name>
	119	--libpods=<name>,...,<name> --verbose
	120
	121	--help - this message
	122	--podpath - colon-separated list of directories containing .pod and
	123	.pm files to be converted (. by default).
	124	--podroot - filesystem base directory from which all relative paths in
	125	podpath stem (default is .).
	126	--htmldir - directory to store resulting html files in relative
	127	to the filesystem (\$podroot/html by default).
	128	--htmlroot - http-server base directory from which all relative paths
	129	in podpath stem (default is /).
	130	--libpods - comma-separated list of files to search for =item pod
	131	directives in as targets of C<> and implicit links (empty
	132	by default).
	133	--norecurse - don't recurse on those subdirectories listed in podpath.
	134	(default behavior).
	135	--recurse - recurse on those subdirectories listed in podpath
	136	--splithead - comma-separated list of .pod or .pm files to split. will
e05c04ea	137	split each file into several smaller files at every occurrence
54310121	138	of a pod =head[1-6] directive.
	139	--splititem - comma-separated list of .pod or .pm files to split using
	140	splitpod.
3e3baf6d	141	--splitpod - directory where the program splitpod can be found
3e3baf6d	142	(\$podroot/pod by default).
54310121	143	--verbose - self-explanatory.
	144
	145	END_OF_USAGE
	146
3d8876fc	147	my (@libpods, @podpath, $podroot, $htmldir, $htmlroot, $recurse, @splithead,
	148	@splititem, $splitpod, $verbose, $pod2html);
	149
54310121	150	@libpods = ();
	151	@podpath = ( "." ); # colon-separated list of directories containing .pod
	152	# and .pm files to be converted.
	153	$podroot = "."; # assume the pods we want are here
	154	$htmldir = ""; # nothing for now...
	155	$htmlroot = "/"; # default value
	156	$recurse = 0; # default behavior
	157	@splithead = (); # don't split any files by default
	158	@splititem = (); # don't split any files by default
	159	$splitpod = ""; # nothing for now.
	160
	161	$verbose = 0; # whether or not to print debugging info
	162
	163	$pod2html = "pod/pod2html";
	164
3e3baf6d	165	usage("") unless @ARGV;
54310121	166
c645ec3f	167	# Overcome shell's p1,..,p8 limitation.
	168	# See vms/descrip_mms.template -> descrip.mms for invokation.
	169	if ( $^O eq 'VMS' ) { @ARGV = split(/\s+/,$ARGV[0]); }
	170
65b03822	171	use vars qw( %Options );
3d8876fc	172
54310121	173	# parse the command-line
65b03822	174	my $result = GetOptions( \%Options, qw(
54310121	175	help
	176	podpath=s
	177	podroot=s
	178	htmldir=s
	179	htmlroot=s
	180	libpods=s
	181	recurse!
	182	splithead=s
	183	splititem=s
	184	splitpod=s
	185	verbose
	186	));
	187	usage("invalid parameters") unless $result;
	188	parse_command_line();
	189
	190
	191	# set these variables to appropriate values if the user didn't specify
	192	# values for them.
	193	$htmldir = "$htmlroot/html" unless $htmldir;
	194	$splitpod = "$podroot/pod" unless $splitpod;
	195
	196
	197	# make sure that the destination directory exists
	198	(mkdir($htmldir, 0755) \|\|
	199	die "$0: cannot make directory $htmldir: $!\n") if ! -d $htmldir;
	200
	201
	202	# the following array will eventually contain files that are to be
	203	# ignored in the conversion process. these are files that have been
	204	# process by splititem or splithead and should not be converted as a
	205	# result.
3d8876fc	206	my @ignore = ();
3d8876fc	207	my @splitdirs;
54310121	208
	209	# split pods. its important to do this before convert ANY pods because
	210	# it may effect some of the links
	211	@splitdirs = (); # files in these directories won't get an index
	212	split_on_head($podroot, $htmldir, \@splitdirs, \@ignore, @splithead);
3e3baf6d	213	split_on_item($podroot, \@splitdirs, \@ignore, @splititem);
54310121	214
	215
	216	# convert the pod pages found in @poddirs
	217	#warn "converting files\n" if $verbose;
	218	#warn "\@ignore\t= @ignore\n" if $verbose;
3d8876fc	219	foreach my $dir (@podpath) {
54310121	220	installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore);
	221	}
	222
	223
	224	# now go through and create master indices for each pod we split
3d8876fc	225	foreach my $dir (@splititem) {
54310121	226	print "creating index $htmldir/$dir.html\n" if $verbose;
	227	create_index("$htmldir/$dir.html", "$htmldir/$dir");
	228	}
	229
3d8876fc	230	foreach my $dir (@splithead) {
776d31fe	231	(my $pod = $dir) =~ s,^.*/,,;
54310121	232	$dir .= ".pod" unless $dir =~ /(\.pod\|\.pm)$/;
	233	# let pod2html create the file
	234	runpod2html($dir, 1);
	235
	236	# now go through and truncate after the index
	237	$dir =~ /^(.*?)(\.pod\|\.pm)?$/sm;
3d8876fc	238	my $file = "$htmldir/$1";
54310121	239	print "creating index $file.html\n" if $verbose;
	240
	241	# read in everything until what would have been the first =head
	242	# directive, patching the index as we go.
	243	open(H, "<$file.html") \|\|
	244	die "$0: error opening $file.html for input: $!\n";
	245	$/ = "";
3d8876fc	246	my @data = ();
54310121	247	while (<H>) {
776d31fe	248	last if /name="name"/i;
	249	$_ =~ s{href="#(.*)">}{
	250	my $url = "$pod/$1.html" ;
	251	$url = Pod::Html::relativize_url( $url, "$file.html" )
	252	if ( ! defined $Options{htmlroot} \|\| $Options{htmlroot} eq '' );
	253	"href=\"$url\">" ;
	254	}egi;
54310121	255	push @data, $_;
776d31fe	256	}
54310121	257	close(H);
	258
	259	# now rewrite the file
	260	open(H, ">$file.html") \|\|
	261	die "$0: error opening $file.html for output: $!\n";
3d8876fc	262	print H "@data", "\n";
54310121	263	close(H);
	264	}
	265
	266	##############################################################################
	267
	268
	269	sub usage {
	270	warn "$0: @_\n" if @_;
	271	die $usage;
	272	}
	273
	274
	275	sub parse_command_line {
65b03822	276	usage() if defined $Options{help};
65b03822	277	$Options{help} = ""; # make -w shut up
54310121	278
54310121	279	# list of directories
65b03822	280	@podpath = split(":", $Options{podpath}) if defined $Options{podpath};
54310121	281
54310121	282	# lists of files
65b03822	283	@splithead = split(",", $Options{splithead}) if defined $Options{splithead};
	284	@splititem = split(",", $Options{splititem}) if defined $Options{splititem};
	285	@libpods = split(",", $Options{libpods}) if defined $Options{libpods};
54310121	286
65b03822	287	$htmldir = $Options{htmldir} if defined $Options{htmldir};
	288	$htmlroot = $Options{htmlroot} if defined $Options{htmlroot};
	289	$podroot = $Options{podroot} if defined $Options{podroot};
	290	$splitpod = $Options{splitpod} if defined $Options{splitpod};
54310121	291
65b03822	292	$recurse = $Options{recurse} if defined $Options{recurse};
65b03822	293	$verbose = $Options{verbose} if defined $Options{verbose};
54310121	294	}
	295
	296
	297	sub create_index {
	298	my($html, $dir) = @_;
df00c672	299	(my $pod = $dir) =~ s,^.*/,,;
54310121	300	my(@files, @filedata, @index, $file);
af19f77d	301	my($lcp1,$lcp2);
af19f77d	302
54310121	303
	304	# get the list of .html files in this directory
	305	opendir(DIR, $dir) \|\|
	306	die "$0: error opening directory $dir for reading: $!\n";
39e571d4	307	@files = sort(grep(/\.html?$/, readdir(DIR)));
54310121	308	closedir(DIR);
	309
	310	open(HTML, ">$html") \|\|
	311	die "$0: error opening $html for output: $!\n";
	312
	313	# for each .html file in the directory, extract the index
	314	# embedded in the file and throw it into the big index.
	315	print HTML "<DL COMPACT>\n";
	316	foreach $file (@files) {
	317	$/ = "";
	318
	319	open(IN, "<$dir/$file") \|\|
	320	die "$0: error opening $dir/$file for input: $!\n";
	321	@filedata = <IN>;
	322	close(IN);
	323
	324	# pull out the NAME section
df00c672	325	my $name;
	326	($name) = grep(/name="name"/i, @filedata);
	327	($lcp1,$lcp2) = ($name =~ m,/H1>\s(\S+)\s[\s-](.?)\s*$,smi);
	328	if (defined $lcp1 and $lcp1 =~ m,^<P>$,i) { # Uninteresting. Try again.
	329	($lcp1,$lcp2) = ($name =~ m,/H1>\s<P>\s(\S+)\s[\s-](.?)\s$,smi);
af19f77d	330	}
df00c672	331	my $url= "$pod/$file" ;
65b03822	332	if ( ! defined $Options{htmlroot} \|\| $Options{htmlroot} eq '' ) {
df00c672	333	$url = Pod::Html::relativize_url( "$pod/$file", $html ) ;
29f227c9	334	}
29f227c9	335
df00c672	336	if (defined $lcp1) {
	337	print HTML qq(<DT><A HREF="$url">);
	338	print HTML "$lcp1</A></DT><DD>$lcp2</DD>\n";
	339	}
54310121	340
	341	next;
	342
	343	@index = grep(/<!-- INDEX BEGIN -->.*<!-- INDEX END -->/s,
	344	@filedata);
	345	for (@index) {
af19f77d	346	s/<!-- INDEX BEGIN -->(\s<!--)(.)(-->\s*)<!-- INDEX END -->/$lcp2/s;
54310121	347	s,#,$dir/$file#,g;
54310121	348	print HTML "$_\n<P><HR><P>\n";
	349	}
	350	}
	351	print HTML "</DL>\n";
	352
	353	close(HTML);
	354	}
	355
	356
	357	sub split_on_head {
	358	my($podroot, $htmldir, $splitdirs, $ignore, @splithead) = @_;
	359	my($pod, $dirname, $filename);
	360
	361	# split the files specified in @splithead on =head[1-6] pod directives
	362	print "splitting files by head.\n" if $verbose && $#splithead >= 0;
	363	foreach $pod (@splithead) {
	364	# figure out the directory name and filename
	365	$pod =~ s,^([^/]*)$,/$1,;
df00c672	366	$pod =~ m,(.)/(.?)(\.pod)?$,;
54310121	367	$dirname = $1;
	368	$filename = "$2.pod";
	369
	370	# since we are splitting this file it shouldn't be converted.
	371	push(@$ignore, "$podroot/$dirname/$filename");
	372
	373	# split the pod
	374	splitpod("$podroot/$dirname/$filename", "$podroot/$dirname", $htmldir,
	375	$splitdirs);
	376	}
	377	}
	378
	379
	380	sub split_on_item {
	381	my($podroot, $splitdirs, $ignore, @splititem) = @_;
	382	my($pwd, $dirname, $filename);
	383
	384	print "splitting files by item.\n" if $verbose && $#splititem >= 0;
	385	$pwd = getcwd();
cac3fadd	386	my $splitter = File::Spec->rel2abs("$splitpod/splitpod", $pwd);
cac3fadd	387	my $perl = File::Spec->rel2abs($^X, $pwd);
3d8876fc	388	foreach my $pod (@splititem) {
54310121	389	# figure out the directory to split into
54310121	390	$pod =~ s,^([^/]*)$,/$1,;
df00c672	391	$pod =~ m,(.)/(.?)(\.pod)?$,;
54310121	392	$dirname = "$1/$2";
	393	$filename = "$2.pod";
	394
	395	# since we are splitting this file it shouldn't be converted.
	396	push(@$ignore, "$podroot/$dirname.pod");
	397
	398	# split the pod
	399	push(@$splitdirs, "$podroot/$dirname");
	400	if (! -d "$podroot/$dirname") {
	401	mkdir("$podroot/$dirname", 0755) \|\|
	402	die "$0: error creating directory $podroot/$dirname: $!\n";
	403	}
	404	chdir("$podroot/$dirname") \|\|
	405	die "$0: error changing to directory $podroot/$dirname: $!\n";
3e3baf6d	406	die "$splitter not found. Use '-splitpod dir' option.\n"
3e3baf6d	407	unless -f $splitter;
ab9905e6	408	system($perl, $splitter, "../$filename") &&
3e3baf6d	409	warn "$0: error running '$splitter ../$filename'"
e05c04ea	410	." from $podroot/$dirname";
54310121	411	}
	412	chdir($pwd);
	413	}
	414
	415
	416	#
	417	# splitpod - splits a .pod file into several smaller .pod files
	418	# where a new file is started each time a =head[1-6] pod directive
	419	# is encountered in the input file.
	420	#
	421	sub splitpod {
	422	my($pod, $poddir, $htmldir, $splitdirs) = @_;
	423	my(@poddata, @filedata, @heads);
	424	my($file, $i, $j, $prevsec, $section, $nextsec);
	425
	426	print "splitting $pod\n" if $verbose;
	427
	428	# read the file in paragraphs
	429	$/ = "";
	430	open(SPLITIN, "<$pod") \|\|
	431	die "$0: error opening $pod for input: $!\n";
	432	@filedata = <SPLITIN>;
	433	close(SPLITIN) \|\|
	434	die "$0: error closing $pod: $!\n";
	435
	436	# restore the file internally by =head[1-6] sections
	437	@poddata = ();
	438	for ($i = 0, $j = -1; $i <= $#filedata; $i++) {
	439	$j++ if ($filedata[$i] =~ /^\s*=head[1-6]/);
	440	if ($j >= 0) {
	441	$poddata[$j] = "" unless defined $poddata[$j];
	442	$poddata[$j] .= "\n$filedata[$i]" if $j >= 0;
	443	}
	444	}
	445
	446	# create list of =head[1-6] sections so that we can rewrite
	447	# L<> links as necessary.
3d8876fc	448	my %heads = ();
54310121	449	foreach $i (0..$#poddata) {
776d31fe	450	$heads{anchorify($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/;
54310121	451	}
	452
	453	# create a directory of a similar name and store all the
	454	# files in there
	455	$pod =~ s,./(.),$1,; # get the last part of the name
3d8876fc	456	my $dir = $pod;
54310121	457	$dir =~ s/\.pod//g;
	458	push(@$splitdirs, "$poddir/$dir");
	459	mkdir("$poddir/$dir", 0755) \|\|
	460	die "$0: could not create directory $poddir/$dir: $!\n"
	461	unless -d "$poddir/$dir";
	462
	463	$poddata[0] =~ /^\s=head[1-6]\s+(.)/;
	464	$section = "";
	465	$nextsec = $1;
	466
	467	# for each section of the file create a separate pod file
	468	for ($i = 0; $i <= $#poddata; $i++) {
	469	# determine the "prev" and "next" links
	470	$prevsec = $section;
	471	$section = $nextsec;
	472	if ($i < $#poddata) {
	473	$poddata[$i+1] =~ /^\s=head[1-6]\s+(.)/;
	474	$nextsec = $1;
	475	} else {
	476	$nextsec = "";
	477	}
	478
	479	# determine an appropriate filename (this must correspond with
	480	# what pod2html will try and guess)
	481	# $poddata[$i] =~ /^\s=head[1-6]\s+(.)/;
776d31fe	482	$file = "$dir/" . anchorify($section) . ".pod";
54310121	483
	484	# create the new .pod file
	485	print "\tcreating $poddir/$file\n" if $verbose;
	486	open(SPLITOUT, ">$poddir/$file") \|\|
	487	die "$0: error opening $poddir/$file for output: $!\n";
	488	$poddata[$i] =~ s,L<([^<>]*)>,
776d31fe	489	defined $heads{anchorify($1)} ? "L<$dir/$1>" : "L<$1>"
776d31fe	490	,ge;
54310121	491	print SPLITOUT $poddata[$i]."\n\n";
	492	print SPLITOUT "=over 4\n\n";
	493	print SPLITOUT "=item *\n\nBack to L<$dir/\"$prevsec\">\n\n" if $prevsec;
	494	print SPLITOUT "=item *\n\nForward to L<$dir/\"$nextsec\">\n\n" if $nextsec;
	495	print SPLITOUT "=item *\n\nUp to L<$dir>\n\n";
	496	print SPLITOUT "=back\n\n";
	497	close(SPLITOUT) \|\|
	498	die "$0: error closing $poddir/$file: $!\n";
	499	}
	500	}
	501
	502
	503	#
	504	# installdir - takes care of converting the .pod and .pm files in the
	505	# current directory to .html files and then installing those.
	506	#
	507	sub installdir {
	508	my($dir, $recurse, $podroot, $splitdirs, $ignore) = @_;
	509	my(@dirlist, @podlist, @pmlist, $doindex);
	510
	511	@dirlist = (); # directories to recurse on
	512	@podlist = (); # .pod files to install
	513	@pmlist = (); # .pm files to install
	514
	515	# should files in this directory get an index?
	516	$doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1);
	517
	518	opendir(DIR, "$podroot/$dir")
	519	\|\| die "$0: error opening directory $podroot/$dir: $!\n";
	520
	521	# find the directories to recurse on
fe4c6be1	522	@dirlist = map { if ($^O eq 'VMS') {/^(.*)\.dir$/i; "$dir/$1";} else {"$dir/$_";}}
54310121	523	grep(-d "$podroot/$dir/$_" && !/^\.{1,2}/, readdir(DIR)) if $recurse;
	524	rewinddir(DIR);
	525
	526	# find all the .pod files within the directory
	527	@podlist = map { /^(.*)\.pod$/; "$dir/$1" }
	528	grep(! -d "$podroot/$dir/$_" && /\.pod$/, readdir(DIR));
	529	rewinddir(DIR);
	530
	531	# find all the .pm files within the directory
	532	@pmlist = map { /^(.*)\.pm$/; "$dir/$1" }
	533	grep(! -d "$podroot/$dir/$_" && /\.pm$/, readdir(DIR));
	534
	535	closedir(DIR);
	536
	537	# recurse on all subdirectories we kept track of
	538	foreach $dir (@dirlist) {
	539	installdir($dir, $recurse, $podroot, $splitdirs, $ignore);
	540	}
	541
	542	# install all the pods we found
3d8876fc	543	foreach my $pod (@podlist) {
54310121	544	# check if we should ignore it.
	545	next if grep($_ eq "$podroot/$pod.pod", @$ignore);
	546
	547	# check if a .pm files exists too
df00c672	548	if (grep($_ eq $pod, @pmlist)) {
54310121	549	print "$0: Warning both `$podroot/$pod.pod' and "
	550	. "`$podroot/$pod.pm' exist, using pod\n";
	551	push(@ignore, "$pod.pm");
	552	}
	553	runpod2html("$pod.pod", $doindex);
	554	}
	555
	556	# install all the .pm files we found
3d8876fc	557	foreach my $pm (@pmlist) {
54310121	558	# check if we should ignore it.
	559	next if grep($_ eq "$pm.pm", @ignore);
	560
	561	runpod2html("$pm.pm", $doindex);
	562	}
	563	}
	564
	565
	566	#
	567	# runpod2html - invokes pod2html to convert a .pod or .pm file to a .html
	568	# file.
	569	#
	570	sub runpod2html {
	571	my($pod, $doindex) = @_;
	572	my($html, $i, $dir, @dirs);
	573
	574	$html = $pod;
	575	$html =~ s/\.(pod\|pm)$/.html/g;
	576
	577	# make sure the destination directories exist
	578	@dirs = split("/", $html);
	579	$dir = "$htmldir/";
	580	for ($i = 0; $i < $#dirs; $i++) {
	581	if (! -d "$dir$dirs[$i]") {
	582	mkdir("$dir$dirs[$i]", 0755) \|\|
	583	die "$0: error creating directory $dir$dirs[$i]: $!\n";
	584	}
	585	$dir .= "$dirs[$i]/";
	586	}
	587
	588	# invoke pod2html
	589	print "$podroot/$pod => $htmldir/$html\n" if $verbose;
df00c672	590	Pod::Html::pod2html(
5a039dd3	591	"--htmldir=$htmldir",
54310121	592	"--htmlroot=$htmlroot",
	593	"--podpath=".join(":", @podpath),
	594	"--podroot=$podroot", "--netscape",
7c82de66	595	"--header",
54310121	596	($doindex ? "--index" : "--noindex"),
	597	"--" . ($recurse ? "" : "no") . "recurse",
	598	($#libpods >= 0) ? "--libpods=" . join(":", @libpods) : "",
	599	"--infile=$podroot/$pod", "--outfile=$htmldir/$html");
	600	die "$0: error running $pod2html: $!\n" if $?;
	601	}