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