[perl5.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;

umask 022;

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