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

#!./perl -w

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

use lib 'lib';		# use source library if present

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

=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

$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

@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;

# parse the command-line
$result = GetOptions( 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.
@ignore = ();


# 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 $dir (@podpath) {
    installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore);
}


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

foreach $dir (@splithead) {
    $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;
    $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";
    $/ = "";
    @data = ();
    while (<H>) {
	last if /NAME=/;
	$_ =~ s{HREF="#(.*)">}{
	    my $url = "$file/$1.html" ;
            $url = Pod::Html::relativize_url( $url, "$file.html" )
                if ( ! defined $opt_htmlroot || $opt_htmlroot eq '' ) ;
            "HREF=\"$url\">" ;
        }eg;
	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 $opt_help;
    $opt_help = ""; 	    	    # make -w shut up

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

    # lists of files
    @splithead = split(",", $opt_splithead) if defined $opt_splithead;
    @splititem = split(",", $opt_splititem) if defined $opt_splititem;
    @libpods   = split(",", $opt_libpods) if defined $opt_libpods;

    $htmldir  = $opt_htmldir	    if defined $opt_htmldir;
    $htmlroot = $opt_htmlroot	    if defined $opt_htmlroot;
    $podroot  = $opt_podroot	    if defined $opt_podroot;
    $splitpod = $opt_splitpod	    if defined $opt_splitpod;

    $recurse  = $opt_recurse	    if defined $opt_recurse;
    $verbose  = $opt_verbose	    if defined $opt_verbose;
}


sub absolute_path {
    my($cwd, $path) = @_;
	return "$cwd/$path" unless $path =~ m:/:;
    # add cwd if path is not already an absolute path
    $path = "$cwd/$path" if (substr($path,0,1) ne '/');
    return $path;
}


sub create_index {
    my($html, $dir) = @_;
    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
	($name) = grep(/NAME=/, @filedata);
	($lcp1,$lcp2) = ($name =~ m,/H1>\s(\S+)\s[\s-]*(.*?)\s*$,sm);
	if (defined $lcp1 and $lcp1 eq '<P>') { # Uninteresting.  Try again.
	   ($lcp1,$lcp2) = ($name =~ m,/H1>\s<P>\s(\S+)\s[\s-]*(.*?)\s*$,sm);
	}
	my $url= "$dir/$file" ;
	if ( ! defined $opt_htmlroot || $opt_htmlroot eq '' ) {
	    $url = Pod::Html::relativize_url( "$dir/$file", $html ) ;
	}

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

	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";
	    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 = absolute_path($pwd, "$splitpod/splitpod");
    foreach $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.
    %heads = ();
    foreach $i (0..$#poddata) {
	$heads{htmlize($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
    $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/" . htmlize($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{htmlize($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 $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.pm", @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 $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;
#system("./pod2html",
        Pod::Html'pod2html(
        #Pod::Html'pod2html($pod2html,
        "--htmldir=$htmldir",
	"--htmlroot=$htmlroot",
	"--podpath=".join(":", @podpath),
	"--podroot=$podroot", "--netscape",
	($doindex ? "--index" : "--noindex"),
	"--" . ($recurse ? "" : "no") . "recurse",
	($#libpods >= 0) ? "--libpods=" . join(":", @libpods) : "",
	"--infile=$podroot/$pod", "--outfile=$htmldir/$html");
    die "$0: error running $pod2html: $!\n" if $?;
}

sub htmlize { htmlify(0, @_) }
Commit	Line	Data
90248788	1	#!./perl -w
	2
	3	# This file should really be a extracted from a .PL
54310121	4
3e3baf6d	5	use lib 'lib'; # use source library if present
3e3baf6d	6
54310121	7	use Config; # for config options in the makefile
	8	use Getopt::Long; # for command-line parsing
	9	use Cwd;
	10	use Pod::Html;
	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
	113	$usage =<<END_OF_USAGE;
	114	Usage: $0 --help --podpath=<name>:...:<name> --podroot=<name>
	115	--htmldir=<name> --htmlroot=<name> --norecurse --recurse
	116	--splithead=<name>,...,<name> --splititem=<name>,...,<name>
	117	--libpods=<name>,...,<name> --verbose
	118
	119	--help - this message
	120	--podpath - colon-separated list of directories containing .pod and
	121	.pm files to be converted (. by default).
	122	--podroot - filesystem base directory from which all relative paths in
	123	podpath stem (default is .).
	124	--htmldir - directory to store resulting html files in relative
	125	to the filesystem (\$podroot/html by default).
	126	--htmlroot - http-server base directory from which all relative paths
	127	in podpath stem (default is /).
	128	--libpods - comma-separated list of files to search for =item pod
	129	directives in as targets of C<> and implicit links (empty
	130	by default).
	131	--norecurse - don't recurse on those subdirectories listed in podpath.
	132	(default behavior).
	133	--recurse - recurse on those subdirectories listed in podpath
	134	--splithead - comma-separated list of .pod or .pm files to split. will
e05c04ea	135	split each file into several smaller files at every occurrence
54310121	136	of a pod =head[1-6] directive.
	137	--splititem - comma-separated list of .pod or .pm files to split using
	138	splitpod.
3e3baf6d	139	--splitpod - directory where the program splitpod can be found
3e3baf6d	140	(\$podroot/pod by default).
54310121	141	--verbose - self-explanatory.
	142
	143	END_OF_USAGE
	144
	145	@libpods = ();
	146	@podpath = ( "." ); # colon-separated list of directories containing .pod
	147	# and .pm files to be converted.
	148	$podroot = "."; # assume the pods we want are here
	149	$htmldir = ""; # nothing for now...
	150	$htmlroot = "/"; # default value
	151	$recurse = 0; # default behavior
	152	@splithead = (); # don't split any files by default
	153	@splititem = (); # don't split any files by default
	154	$splitpod = ""; # nothing for now.
	155
	156	$verbose = 0; # whether or not to print debugging info
	157
	158	$pod2html = "pod/pod2html";
	159
3e3baf6d	160	usage("") unless @ARGV;
54310121	161
	162	# parse the command-line
	163	$result = GetOptions( qw(
	164	help
	165	podpath=s
	166	podroot=s
	167	htmldir=s
	168	htmlroot=s
	169	libpods=s
	170	recurse!
	171	splithead=s
	172	splititem=s
	173	splitpod=s
	174	verbose
	175	));
	176	usage("invalid parameters") unless $result;
	177	parse_command_line();
	178
	179
	180	# set these variables to appropriate values if the user didn't specify
	181	# values for them.
	182	$htmldir = "$htmlroot/html" unless $htmldir;
	183	$splitpod = "$podroot/pod" unless $splitpod;
	184
	185
	186	# make sure that the destination directory exists
	187	(mkdir($htmldir, 0755) \|\|
	188	die "$0: cannot make directory $htmldir: $!\n") if ! -d $htmldir;
	189
	190
	191	# the following array will eventually contain files that are to be
	192	# ignored in the conversion process. these are files that have been
	193	# process by splititem or splithead and should not be converted as a
	194	# result.
	195	@ignore = ();
	196
	197
	198	# split pods. its important to do this before convert ANY pods because
	199	# it may effect some of the links
	200	@splitdirs = (); # files in these directories won't get an index
	201	split_on_head($podroot, $htmldir, \@splitdirs, \@ignore, @splithead);
3e3baf6d	202	split_on_item($podroot, \@splitdirs, \@ignore, @splititem);
54310121	203
	204
	205	# convert the pod pages found in @poddirs
	206	#warn "converting files\n" if $verbose;
	207	#warn "\@ignore\t= @ignore\n" if $verbose;
	208	foreach $dir (@podpath) {
	209	installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore);
	210	}
	211
	212
	213	# now go through and create master indices for each pod we split
	214	foreach $dir (@splititem) {
	215	print "creating index $htmldir/$dir.html\n" if $verbose;
	216	create_index("$htmldir/$dir.html", "$htmldir/$dir");
	217	}
	218
	219	foreach $dir (@splithead) {
	220	$dir .= ".pod" unless $dir =~ /(\.pod\|\.pm)$/;
	221	# let pod2html create the file
	222	runpod2html($dir, 1);
	223
	224	# now go through and truncate after the index
	225	$dir =~ /^(.*?)(\.pod\|\.pm)?$/sm;
	226	$file = "$htmldir/$1";
	227	print "creating index $file.html\n" if $verbose;
	228
	229	# read in everything until what would have been the first =head
	230	# directive, patching the index as we go.
	231	open(H, "<$file.html") \|\|
	232	die "$0: error opening $file.html for input: $!\n";
	233	$/ = "";
	234	@data = ();
	235	while (<H>) {
	236	last if /NAME=/;
29f227c9	237	$_ =~ s{HREF="#(.*)">}{
	238	my $url = "$file/$1.html" ;
	239	$url = Pod::Html::relativize_url( $url, "$file.html" )
	240	if ( ! defined $opt_htmlroot \|\| $opt_htmlroot eq '' ) ;
	241	"HREF=\"$url\">" ;
	242	}eg;
54310121	243	push @data, $_;
	244	}
	245	close(H);
	246
	247	# now rewrite the file
	248	open(H, ">$file.html") \|\|
	249	die "$0: error opening $file.html for output: $!\n";
	250	print H "@data\n";
	251	close(H);
	252	}
	253
	254	##############################################################################
	255
	256
	257	sub usage {
	258	warn "$0: @_\n" if @_;
	259	die $usage;
	260	}
	261
	262
	263	sub parse_command_line {
	264	usage() if defined $opt_help;
	265	$opt_help = ""; # make -w shut up
	266
	267	# list of directories
	268	@podpath = split(":", $opt_podpath) if defined $opt_podpath;
	269
	270	# lists of files
	271	@splithead = split(",", $opt_splithead) if defined $opt_splithead;
	272	@splititem = split(",", $opt_splititem) if defined $opt_splititem;
	273	@libpods = split(",", $opt_libpods) if defined $opt_libpods;
	274
	275	$htmldir = $opt_htmldir if defined $opt_htmldir;
	276	$htmlroot = $opt_htmlroot if defined $opt_htmlroot;
	277	$podroot = $opt_podroot if defined $opt_podroot;
	278	$splitpod = $opt_splitpod if defined $opt_splitpod;
	279
	280	$recurse = $opt_recurse if defined $opt_recurse;
	281	$verbose = $opt_verbose if defined $opt_verbose;
	282	}
	283
	284
3e3baf6d	285	sub absolute_path {
	286	my($cwd, $path) = @_;
	287	return "$cwd/$path" unless $path =~ m:/:;
	288	# add cwd if path is not already an absolute path
	289	$path = "$cwd/$path" if (substr($path,0,1) ne '/');
	290	return $path;
	291	}
	292
	293
54310121	294	sub create_index {
	295	my($html, $dir) = @_;
	296	my(@files, @filedata, @index, $file);
af19f77d	297	my($lcp1,$lcp2);
af19f77d	298
54310121	299
	300	# get the list of .html files in this directory
	301	opendir(DIR, $dir) \|\|
	302	die "$0: error opening directory $dir for reading: $!\n";
39e571d4	303	@files = sort(grep(/\.html?$/, readdir(DIR)));
54310121	304	closedir(DIR);
	305
	306	open(HTML, ">$html") \|\|
	307	die "$0: error opening $html for output: $!\n";
	308
	309	# for each .html file in the directory, extract the index
	310	# embedded in the file and throw it into the big index.
	311	print HTML "<DL COMPACT>\n";
	312	foreach $file (@files) {
	313	$/ = "";
	314
	315	open(IN, "<$dir/$file") \|\|
	316	die "$0: error opening $dir/$file for input: $!\n";
	317	@filedata = <IN>;
	318	close(IN);
	319
	320	# pull out the NAME section
	321	($name) = grep(/NAME=/, @filedata);
af19f77d	322	($lcp1,$lcp2) = ($name =~ m,/H1>\s(\S+)\s[\s-](.?)\s*$,sm);
	323	if (defined $lcp1 and $lcp1 eq '<P>') { # Uninteresting. Try again.
	324	($lcp1,$lcp2) = ($name =~ m,/H1>\s<P>\s(\S+)\s[\s-](.?)\s*$,sm);
	325	}
29f227c9	326	my $url= "$dir/$file" ;
	327	if ( ! defined $opt_htmlroot \|\| $opt_htmlroot eq '' ) {
	328	$url = Pod::Html::relativize_url( "$dir/$file", $html ) ;
	329	}
	330
	331	print HTML qq(<A HREF="$url">);
af19f77d	332	print HTML "<DT>$lcp1</A><DD>$lcp2\n" if defined $lcp1;
29f227c9	333	# print HTML qq(<A HREF="$url">$lcp1</A><BR>\n") if defined $lcp1;
54310121	334
	335	next;
	336
	337	@index = grep(/<!-- INDEX BEGIN -->.*<!-- INDEX END -->/s,
	338	@filedata);
	339	for (@index) {
af19f77d	340	s/<!-- INDEX BEGIN -->(\s<!--)(.)(-->\s*)<!-- INDEX END -->/$lcp2/s;
54310121	341	s,#,$dir/$file#,g;
	342	# print HTML "$_\n";
	343	print HTML "$_\n<P><HR><P>\n";
	344	}
	345	}
	346	print HTML "</DL>\n";
	347
	348	close(HTML);
	349	}
	350
	351
	352	sub split_on_head {
	353	my($podroot, $htmldir, $splitdirs, $ignore, @splithead) = @_;
	354	my($pod, $dirname, $filename);
	355
	356	# split the files specified in @splithead on =head[1-6] pod directives
	357	print "splitting files by head.\n" if $verbose && $#splithead >= 0;
	358	foreach $pod (@splithead) {
	359	# figure out the directory name and filename
	360	$pod =~ s,^([^/]*)$,/$1,;
	361	$pod =~ m,(.?)/(.?)(\.pod)?$,;
	362	$dirname = $1;
	363	$filename = "$2.pod";
	364
	365	# since we are splitting this file it shouldn't be converted.
	366	push(@$ignore, "$podroot/$dirname/$filename");
	367
	368	# split the pod
	369	splitpod("$podroot/$dirname/$filename", "$podroot/$dirname", $htmldir,
	370	$splitdirs);
	371	}
	372	}
	373
	374
	375	sub split_on_item {
	376	my($podroot, $splitdirs, $ignore, @splititem) = @_;
	377	my($pwd, $dirname, $filename);
	378
	379	print "splitting files by item.\n" if $verbose && $#splititem >= 0;
	380	$pwd = getcwd();
3e3baf6d	381	my $splitter = absolute_path($pwd, "$splitpod/splitpod");
54310121	382	foreach $pod (@splititem) {
	383	# figure out the directory to split into
	384	$pod =~ s,^([^/]*)$,/$1,;
	385	$pod =~ m,(.?)/(.?)(\.pod)?$,;
	386	$dirname = "$1/$2";
	387	$filename = "$2.pod";
	388
	389	# since we are splitting this file it shouldn't be converted.
	390	push(@$ignore, "$podroot/$dirname.pod");
	391
	392	# split the pod
	393	push(@$splitdirs, "$podroot/$dirname");
	394	if (! -d "$podroot/$dirname") {
	395	mkdir("$podroot/$dirname", 0755) \|\|
	396	die "$0: error creating directory $podroot/$dirname: $!\n";
	397	}
	398	chdir("$podroot/$dirname") \|\|
	399	die "$0: error changing to directory $podroot/$dirname: $!\n";
3e3baf6d	400	die "$splitter not found. Use '-splitpod dir' option.\n"
	401	unless -f $splitter;
	402	system("perl", $splitter, "../$filename") &&
	403	warn "$0: error running '$splitter ../$filename'"
e05c04ea	404	." from $podroot/$dirname";
54310121	405	}
	406	chdir($pwd);
	407	}
	408
	409
	410	#
	411	# splitpod - splits a .pod file into several smaller .pod files
	412	# where a new file is started each time a =head[1-6] pod directive
	413	# is encountered in the input file.
	414	#
	415	sub splitpod {
	416	my($pod, $poddir, $htmldir, $splitdirs) = @_;
	417	my(@poddata, @filedata, @heads);
	418	my($file, $i, $j, $prevsec, $section, $nextsec);
	419
	420	print "splitting $pod\n" if $verbose;
	421
	422	# read the file in paragraphs
	423	$/ = "";
	424	open(SPLITIN, "<$pod") \|\|
	425	die "$0: error opening $pod for input: $!\n";
	426	@filedata = <SPLITIN>;
	427	close(SPLITIN) \|\|
	428	die "$0: error closing $pod: $!\n";
	429
	430	# restore the file internally by =head[1-6] sections
	431	@poddata = ();
	432	for ($i = 0, $j = -1; $i <= $#filedata; $i++) {
	433	$j++ if ($filedata[$i] =~ /^\s*=head[1-6]/);
	434	if ($j >= 0) {
	435	$poddata[$j] = "" unless defined $poddata[$j];
	436	$poddata[$j] .= "\n$filedata[$i]" if $j >= 0;
	437	}
	438	}
	439
	440	# create list of =head[1-6] sections so that we can rewrite
	441	# L<> links as necessary.
	442	%heads = ();
	443	foreach $i (0..$#poddata) {
	444	$heads{htmlize($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/;
	445	}
	446
	447	# create a directory of a similar name and store all the
	448	# files in there
	449	$pod =~ s,./(.),$1,; # get the last part of the name
	450	$dir = $pod;
	451	$dir =~ s/\.pod//g;
	452	push(@$splitdirs, "$poddir/$dir");
	453	mkdir("$poddir/$dir", 0755) \|\|
	454	die "$0: could not create directory $poddir/$dir: $!\n"
	455	unless -d "$poddir/$dir";
	456
	457	$poddata[0] =~ /^\s=head[1-6]\s+(.)/;
	458	$section = "";
	459	$nextsec = $1;
	460
	461	# for each section of the file create a separate pod file
	462	for ($i = 0; $i <= $#poddata; $i++) {
	463	# determine the "prev" and "next" links
	464	$prevsec = $section;
	465	$section = $nextsec;
	466	if ($i < $#poddata) {
	467	$poddata[$i+1] =~ /^\s=head[1-6]\s+(.)/;
	468	$nextsec = $1;
469	} else {
470	$nextsec = "";
471	}
472
473	# determine an appropriate filename (this must correspond with
474	# what pod2html will try and guess)
475	# $poddata[$i] =~ /^\s=head[1-6]\s+(.)/;
476	$file = "$dir/" . htmlize($section) . ".pod";
477
478	# create the new .pod file
479	print "\tcreating $poddir/$file\n" if $verbose;
480	open(SPLITOUT, ">$poddir/$file") \|\|
481	die "$0: error opening $poddir/$file for output: $!\n";
482	$poddata[$i] =~ s,L<([^<>]*)>,
483	defined $heads{htmlize($1)} ? "L<$dir/$1>" : "L<$1>"
484	,ge;
485	print SPLITOUT $poddata[$i]."\n\n";
486	print SPLITOUT "=over 4\n\n";
487	print SPLITOUT "=item *\n\nBack to L<$dir/\"$prevsec\">\n\n" if $prevsec;
488	print SPLITOUT "=item *\n\nForward to L<$dir/\"$nextsec\">\n\n" if $nextsec;
489	print SPLITOUT "=item *\n\nUp to L<$dir>\n\n";
490	print SPLITOUT "=back\n\n";
491	close(SPLITOUT) \|\|
492	die "$0: error closing $poddir/$file: $!\n";
493	}
494	}
495
496
497	#
498	# installdir - takes care of converting the .pod and .pm files in the
499	# current directory to .html files and then installing those.
500	#
501	sub installdir {
502	my($dir, $recurse, $podroot, $splitdirs, $ignore) = @_;
503	my(@dirlist, @podlist, @pmlist, $doindex);
504
505	@dirlist = (); # directories to recurse on
506	@podlist = (); # .pod files to install
507	@pmlist = (); # .pm files to install
508
509	# should files in this directory get an index?
510	$doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1);
511
512	opendir(DIR, "$podroot/$dir")
513	\|\| die "$0: error opening directory $podroot/$dir: $!\n";
514
515	# find the directories to recurse on
fe4c6be1	516	@dirlist = map { if ($^O eq 'VMS') {/^(.*)\.dir$/i; "$dir/$1";} else {"$dir/$_";}}
54310121	517	grep(-d "$podroot/$dir/$_" && !/^\.{1,2}/, readdir(DIR)) if $recurse;
	518	rewinddir(DIR);
	519
	520	# find all the .pod files within the directory
	521	@podlist = map { /^(.*)\.pod$/; "$dir/$1" }
	522	grep(! -d "$podroot/$dir/$_" && /\.pod$/, readdir(DIR));
	523	rewinddir(DIR);
	524
	525	# find all the .pm files within the directory
	526	@pmlist = map { /^(.*)\.pm$/; "$dir/$1" }
	527	grep(! -d "$podroot/$dir/$_" && /\.pm$/, readdir(DIR));
	528
	529	closedir(DIR);
	530
	531	# recurse on all subdirectories we kept track of
	532	foreach $dir (@dirlist) {
	533	installdir($dir, $recurse, $podroot, $splitdirs, $ignore);
	534	}
	535
	536	# install all the pods we found
	537	foreach $pod (@podlist) {
	538	# check if we should ignore it.
	539	next if grep($_ eq "$podroot/$pod.pod", @$ignore);
	540
	541	# check if a .pm files exists too
	542	if (grep($_ eq "$pod.pm", @pmlist)) {
	543	print "$0: Warning both `$podroot/$pod.pod' and "
	544	. "`$podroot/$pod.pm' exist, using pod\n";
	545	push(@ignore, "$pod.pm");
	546	}
	547	runpod2html("$pod.pod", $doindex);
	548	}
	549
	550	# install all the .pm files we found
	551	foreach $pm (@pmlist) {
	552	# check if we should ignore it.
	553	next if grep($_ eq "$pm.pm", @ignore);
	554
	555	runpod2html("$pm.pm", $doindex);
	556	}
	557	}
	558
	559
	560	#
	561	# runpod2html - invokes pod2html to convert a .pod or .pm file to a .html
	562	# file.
	563	#
	564	sub runpod2html {
	565	my($pod, $doindex) = @_;
	566	my($html, $i, $dir, @dirs);
	567
	568	$html = $pod;
	569	$html =~ s/\.(pod\|pm)$/.html/g;
	570
	571	# make sure the destination directories exist
	572	@dirs = split("/", $html);
	573	$dir = "$htmldir/";
	574	for ($i = 0; $i < $#dirs; $i++) {
	575	if (! -d "$dir$dirs[$i]") {
	576	mkdir("$dir$dirs[$i]", 0755) \|\|
	577	die "$0: error creating directory $dir$dirs[$i]: $!\n";
	578	}
	579	$dir .= "$dirs[$i]/";
	580	}
581
582	# invoke pod2html
583	print "$podroot/$pod => $htmldir/$html\n" if $verbose;
584	#system("./pod2html",
585	Pod::Html'pod2html(
586	#Pod::Html'pod2html($pod2html,
5a039dd3	587	"--htmldir=$htmldir",
54310121	588	"--htmlroot=$htmlroot",
	589	"--podpath=".join(":", @podpath),
	590	"--podroot=$podroot", "--netscape",
	591	($doindex ? "--index" : "--noindex"),
	592	"--" . ($recurse ? "" : "no") . "recurse",
	593	($#libpods >= 0) ? "--libpods=" . join(":", @libpods) : "",
	594	"--infile=$podroot/$pod", "--outfile=$htmldir/$html");
	595	die "$0: error running $pod2html: $!\n" if $?;
	596	}
	597
	598	sub htmlize { htmlify(0, @_) }