[inseperable changes from patch from perl-5.003_95 to perl-5.003_86]

[editor's note: this commit was prepared manually so may differ in
minor ways to other inseperable changes commits]

 CORE LANGUAGE CHANGES

  Title:  "Support $ENV{PERL5OPT}"
   From:  Chip Salzenberg
  Files:  perl.c pod/perldiag.pod pod/perldelta.pod pod/perlrun.pod

  Title:  "Implement void context, in which C<wantarray> is undef"
   From:  Chip Salzenberg
  Files:  cop.h doop.c dump.c global.sym gv.c op.c op.h perl.c
          pod/perlcall.pod pod/perldelta.pod pod/perlfunc.pod
          pod/perlguts.pod pod/perlsub.pod pp.c pp_ctl.c pp_hot.c
          pp_sys.c proto.h

  Title:  "Don't look up &AUTOLOAD in @ISA when calling plain function"
   From:  Chip Salzenberg
  Files:  global.sym gv.c lib/Text/ParseWords.pm pod/perldelta.pod
          pp_hot.c proto.h t/op/method.t

  Title:  "Allow closures to be constant subroutines"
   From:  Chip Salzenberg
  Files:  op.c

  Title:  "Make C<scalar(reverse)> mean C<scalar(reverse $_)>"
   From:  Chip Salzenberg
  Files:  pp.c

  Title:  "Fix lexical suicide from C<my $x = $x> in sub"
   From:  Chip Salzenberg
  Files:  op.c

  Title:  "Make "Unrecog. char." fatal, and update its doc"
   From:  Chip Salzenberg
  Files:  pod/perldiag.pod toke.c

 CORE PORTABILITY

  Title:  "safefree() mismatch"
   From:  Roderick Schertler
 Msg-ID:  <21338.859653381@eeyore.ibcinc.com>
   Date:  Sat, 29 Mar 1997 11:36:21 -0500
  Files:  util.c

    (applied based on p5p patch as commit id 9b9b466fb02dc96c81439bafbb3b2da55238cfd2)

  Title:  "Win32 update (seven patches)"
   From:  Gurusamy Sarathy and Nick Ing-Simmons
  Files:  EXTERN.h MANIFEST win32/Makefile win32/perl.mak
          win32/perl.rc win32/perldll.mak win32/makedef.pl
          win32/modules.mak win32/win32io.c win32/bin/pl2bat.bat

 OTHER CORE CHANGES

  Title:  "Report PERL* environment variables in -V and perlbug"
   From:  Chip Salzenberg
  Files:  perl.c utils/perlbug.PL

  Title:  "Typo in perl.c: Printing NO_EMBED for perl -V"
   From:  Gisle Aas
 Msg-ID:  <199703301922.VAA13509@furubotn.sn.no>
   Date:  Sun, 30 Mar 1997 21:22:11 +0200
  Files:  perl.c

    (applied based on p5p patch as commit id b6c639e4b1912ad03b9b10ba9518d96bd0a6cfaf)

  Title:  "Don't let C<$var = $var> untaint $var"
   From:  Chip Salzenberg
  Files:  pp_hot.c pp_sys.c sv.h t/op/taint.t

  Title:  "Fix autoviv bug in C<my $x; ++$x->{KEY}>"
   From:  Chip Salzenberg
  Files:  pp_hot.c

  Title:  "Re: 5.004's new srand() default seed"
   From:  Hallvard B Furuseth
 Msg-ID:  <199703302219.AAA20998@bombur2.uio.no>
   Date:  Mon, 31 Mar 1997 00:19:13 +0200 (MET DST)
  Files:  pp.c

    (applied based on p5p patch as commit id d7d933a26349f945f93b2f0dbf85b773d8ca3219)

  Title:  "Re: embedded perl and top_env problem "
   From:  Gurusamy Sarathy
 Msg-ID:  <199703280031.TAA05711@aatma.engin.umich.edu>
   Date:  Thu, 27 Mar 1997 19:31:42 -0500
  Files:  gv.c interp.sym perl.c perl.h pp_ctl.c pp_sys.c scope.h util.c

    (applied based on p5p patch as commit id f289f7d2518e7a8a82114282e774adf50fa6ce85)

  Title:  "Define and use new macro: boolSV()"
   From:  Tim Bunce
  Files:  gv.c lib/ExtUtils/typemap os2/os2.c pp.c pp_hot.c pp_sys.c
          sv.c sv.h universal.c vms/vms.c

  Title:  "Re: strict @F"
   From:  Hallvard B Furuseth
 Msg-ID:  <199703252110.WAA16038@bombur2.uio.no>
   Date:  Tue, 25 Mar 1997 22:10:33 +0100 (MET)
  Files:  toke.c

    (applied based on p5p patch as commit id dfd44a5c8c8dd4c001c595debfe73d011a96d844)

  Title:  "Try harder to identify errors at EOF"
   From:  Chip Salzenberg
  Files:  toke.c

  Title:  "Minor string change in toke.c: 'bareword'"
   From:  lvirden@cas.org
 Msg-ID:  <1997Mar27.130247.1911552@hmivax.humgen.upenn.edu>
   Date:  Thu, 27 Mar 1997 13:02:46 -0500 (EST)
  Files:  toke.c

    (applied based on p5p patch as commit id 9b56c8f8085a9e773ad87c6b3c1d0b5e39dbc348)

  Title:  "Improve diagnostic on \r in program text"
   From:  Chip Salzenberg
  Files:  pod/perldiag.pod toke.c

  Title:  "Make Sock_size_t typedef work right"
   From:  Chip Salzenberg
  Files:  perl.h pp_sys.c

 LIBRARY AND EXTENSIONS

  Title:  "New module constant.pm"
   From:  Tom Phoenix
  Files:  MANIFEST lib/constant.pm op.c pp.c t/pragma/constant.t

  Title:  "Remove chat2"
   From:  Chip Salzenberg
  Files:  MANIFEST lib/chat2.inter lib/chat2.pl

  Title:  "Include CGI.pm 2.32"
   From:  Chip Salzenberg
  Files:  MANIFEST eg/cgi/* lib/CGI.pm lib/CGI/Apache.pm
          lib/CGI/Carp.pm lib/CGI/Fast.pm lib/CGI/Push.pm
          lib/CGI/Switch.pm

 UTILITIES

  Title:  "Tom C's Pod::Html and html tools, as of 30 March 97"
   From:  Chip Salzenberg
  Files:  MANIFEST installhtml lib/Pod/Html.pm pod/pod2html.PL

  Title:  "Fix path bugs in installhtml"
   From:  Robin Barker <rmb1@cise.npl.co.uk>
 Msg-ID:  <3180.9703270906@tempest.cise.npl.co.uk>
   Date:  Thu, 27 Mar 97 09:06:14 GMT
  Files:  installhtml

  Title:  "Make perlbug say that it's only for core Perl bugs"
   From:  Chip Salzenberg
  Files:  utils/perlbug.PL

 DOCUMENTATION

  Title:  "Document autouse and constant; update diagnostics"
   From:  Chip Salzenberg
  Files:  pod/perldelta.pod

  Title:  "Suggest to upgraders that they try '-w' again"
   From:  Hallvard B Furuseth
 Msg-ID:  <199703251901.UAA15982@bombur2.uio.no>
   Date:  Tue, 25 Mar 1997 20:01:26 +0100 (MET)
  Files:  pod/perldelta.pod

    (applied based on p5p patch as commit id 4176c059b9ba6b022e99c44270434a5c3e415b73)

  Title:  "Improve and update documentation of constant subs"
   From:  Tom Phoenix <rootbeer@teleport.com>
 Msg-ID:  <Pine.GSO.3.96.970331122546.14185C-100000@kelly.teleport.com>
   Date:  Mon, 31 Mar 1997 13:05:54 -0800 (PST)
  Files:  pod/perlsub.pod

  Title:  "Improve documentation of C<return>"
   From:  Chip Salzenberg
  Files:  pod/perlfunc.pod pod/perlsub.pod

  Title:  "perlfunc.pod patch"
   From:  Gisle Aas
 Msg-ID:  <199703262159.WAA17531@furubotn.sn.no>
   Date:  Wed, 26 Mar 1997 22:59:23 +0100
  Files:  pod/perlfunc.pod

    (applied based on p5p patch as commit id 35a731fcbcd7860eb497d6598f3f77b8746319c4)

  Title:  "Use 'while (defined($x = <>)) {}', per <gnat@frii.com>"
   From:  Chip Salzenberg
  Files:  configpm lib/Term/Cap.pm perlsh pod/perlipc.pod pod/perlop.pod
          pod/perlsub.pod pod/perlsyn.pod pod/perltrap.pod
          pod/perlvar.pod win32/bin/search.bat

  Title:  "Document and test C<%> behavior with negative operands"
   From:  Chip Salzenberg
  Files:  pod/perlop.pod t/op/arith.t

  Title:  "Update docs on $]"
   From:  Chip Salzenberg
  Files:  pod/perlvar.pod

  Title:  "perlvar.pod patch"
   From:  Gisle Aas
 Msg-ID:  <199703261254.NAA10237@bergen.sn.no>
   Date:  Wed, 26 Mar 1997 13:54:00 +0100
  Files:  pod/perlvar.pod

    (applied based on p5p patch as commit id 0aa182cb0caa3829032904b9754807b1b7418509)

  Title:  "Fix example of C<or> vs. C<||>"
   From:  Chip Salzenberg
  Files:  pod/perlsyn.pod

  Title:  "Pod usage and spelling patch"
   From:  Larry W. Virden
  Files:  pod/*.pod

  Title:  "Pod updates"
   From:  "Cary D. Renzema" <caryr@mxim.com>
 Msg-ID:  <199703262353.PAA01819@macs.mxim.com>
   Date:  Wed, 26 Mar 1997 15:53:22 -0800 (PST)
  Files:  pod/*.pod

    (applied based on p5p patch as commit id 5695b28edc67a3f45e8a0f25755d07afef3660ac)

1 files changed, 139 insertions, 647 deletions

diff --git a/pod/pod2html.PL b/pod/pod2html.PL
index 1c53f6c090..de36cd7fc9 100644
--- a/pod/pod2html.PL
+++ b/pod/pod2html.PL
@@ -32,655 +32,147 @@ $Config{startperl}
 # In the following, perl variables are not expanded during extraction.
 
 print OUT <<'!NO!SUBS!';
+=pod
 
-#
-# pod2html - convert pod format to html
-# Version 1.21
-# usage: pod2html [podfiles]
-# Will read the cwd and parse all files with .pod extension
-# if no arguments are given on the command line.
-#
-# Many helps, suggestions, and fixes from the perl5 porters, and all over.
-# Bill Middleton - wjm@metronet.com
-#
-# Please send patches/fixes/features to me
-#
-
-require 'find.pl';
-
-*RS = */;
-*ERRNO = *!;
-
-
-################################################################################
-# Invoke with various levels of debugging possible
-################################################################################
-while ($ARGV[0] =~ /^-d(.*)/) {
-    shift;
-    $Debug{ lc($1 || shift) }++;
-}
-
-# ck for podnames on command line
-while ($ARGV[0]) {
-    push(@Pods,shift);
-}
-
-################################################################################
-# CONFIGURE -  change the following to suit your OS and taste
-################################################################################
-# The beginning of the url for the anchors to the other sections.
-# Edit $type to suit.  It's configured for relative url's now.
-# Other possibilities are:
-# $type = '<A HREF="file://localhost/usr/local/htmldir/'; # file url
-# $type = '<A HREF="http://www.bozo.com/perl/manual/html/' # server
-
-$type = '<A HREF="';		
-
-################################################################################
-# location of all podfiles unless on command line
-# $installprivlib='HD:usr:local:lib:perl5'; # uncomment for Mac
-# $installprivlib='C:\usr\local\lib\perl5'; # uncomment for DOS (I hope)
-# $installprivlib='/usr/local/lib/perl5'; # Unix
-$installprivlib="./"; # Standard perl pod directory for intallation
-
-################################################################################
-# Where to write out the html files
-# $installhtmldir='HD:usr:local:lib:perl5:html'; # uncomment for Mac
-# $installhtmldir='C:\usr\local\lib\perl5\html'; # uncomment for DOS (I hope)
-$installhtmldir = './'; 
-
-# test for validness
-
-if(!(-d $installhtmldir)){
-    print "Installation directory $installhtmldir does not exist, using cwd\n";
-    print "Hit ^C now to edit this script and configure installhtmldir\n";
-    $installhtmldir = '.';
-}
-
-################################################################################
-# the html extension, change to htm for DOS 
-
-$htmlext = "html"; 
-
-################################################################################
-# arbitrary name for this group of pods
-
-$package = "perl";  
-
-################################################################################
-# look in these pods for links to things not found within the current pod
-# be careful tho, namespace collisions cause stupid links
-
-@inclusions = qw[ perlfunc perlvar perlrun perlop ];
-
-################################################################################
-# Directory path separator
-# $sep= ":"; # uncomment for Mac 
-# $sep= "\"; # uncomment for DOS 
-
-$sep= "/";          
-
-################################################################################
-# Create 8.3 html files if this equals 1
-
-$DOSify=0;          
-
-################################################################################
-# Create maximum 32 character html files if this equals 1
-$MACify=0;
-
-################################################################################
-# END CONFIGURE
-# Beyond here be dragons.  :-)
-################################################################################
-
-$A = {};  # The beginning of all things
-
-unless(@Pods){  
-    find($installprivlib);
-    splice(@Pods,$#Pods+1,0,@modpods);;
-}
-
-@Pods or die "aak, expected pods";
-open(INDEX,">".$installhtmldir.$sep."index.".$htmlext) or 
-	(die "cant open index.$htmlext");
-print INDEX "\n<HTML>\n<HEAD>\n<TITLE>Index of all pods for $package</TITLE></HEAD>\n<BODY>\n";
-print INDEX "<H1>Index of all pods for $package</H1>\n<hr><UL>\n";
-# loop twice through the pods, first to learn the links, then to produce html
-for $count (0,1) {
-    print STDERR "Scanning pods...\n" unless $count;
-loop1:
-    foreach $podfh ( @Pods ) {
-	$didindex = 0;
-	$refname = $podfh;
-	$refname =~ s/\Q$installprivlib${sep}\E?//;
-	$refname =~ s/${sep}/::/g;
-	$refname =~ s/\.p(m|od)$//;
-	$refname =~ s/^pod:://;
-	$savename = $refname;
-	$refname =~ s/::/_/g;  
-	if($DOSify && !$count){  # shorten the name for DOS
-	    (length($refname) > 8) and ( $refname = substr($refname,0,8));
-	    while(defined($DosNames{$refname})){
-        	@refname=split(//,$refname);
-		# allow 25 of em
-                ($refname[$#refname] eq "z") and ($refname[$#refname]  = "a");
-                $refname[$#refname]++;
-                $refname=join('',@refname);
-                $refname =~ s/\W/_/g;
-	    }
-	    $DosNames{$refname} = 1;
-	    $Podnames{$savename} = $refname . ".$htmlext";
-	}
-	elsif(!$DOSify and !$count){
-	    $Podnames{$savename} = $refname . ".$htmlext";
-	}
-        $pod = $savename;
-	Debug("files", "opening 2 $podfh" );
-	print "Creating $Podnames{$savename} from $podfh\n" if $count;
-	$RS = "\n=";         # grok pods by item (Nonstandard but effecient)
-	open($podfh,"<".$podfh)  || die "can't open $podfh: $ERRNO";
-	@all = <$podfh>;
-	close($podfh);
-	$RS = "\n";
-        ($all[0] =~ s/^=//) || pop(@all);
-        for ($i=0;$i <= $#all;$i++){ splice(@all,$i+1,1) unless 
-			(($all[$i] =~ s/=$//) && ($all[$i+1] !~ /^cut/)) ; # whoa..
-	}
-	$in_list = 0;
-	unless (grep(/NAME/,@all)){
-	    print STDERR "NAME header not found in $podfh, skipping\n";
-	    #delete($Podnames{$savename});
-	    next loop1;
-	}
-	if ($count) {   
-	    next unless length($Podnames{$savename});
-	    open(HTML,">".$installhtmldir.$sep.$Podnames{$savename}) or 
-		(die "can't create $Podnames{$savename}: $ERRNO");
-        print HTML "<HTML><HEAD>";
-        print HTML "<TITLE>$refname</TITLE>\n</HEAD>\n<BODY>";
-    }
-
-	for ($i = 0; $i <= $#all; $i++) {       # decide what to do with each chunk
-	    $all[$i] =~ /^(\w+)\s*(.*)\n?([^\0]*)$/ ;
-	    ($cmd, $title, $rest) = ($1,$2,$3);
-	    if(length($cmd)){$cutting =0;}
-	    next if $cutting;
-	    if(($title  =~ /NAME/) and ($didindex == 0) and $count){
-		print INDEX "<LI><A HREF=\"$Podnames{$savename}\">$rest</A>\n";
-		$didindex=1;
-	    }
-	    if ($cmd eq "item") {
-		if ($count ) { # producing html
-		    do_list("over",$all[$i],\$in_list,\$depth) unless $depth;
-		    do_item($title,$rest,$in_list);
-		}
-		else {  
-		    # scan item
-		    scan_thing("item",$title,$pod);
-		}
-	    }
-	    elsif ($cmd =~ /^head([12])/) {
-		$num = $1;
-		if ($count) { # producing html
-		    do_hdr($num,$title,$rest,$depth);
-		}
-		else {
-		    # header scan
-		    scan_thing($cmd,$title,$pod); # skip head1
-		}
-	    }
-	    elsif ($cmd =~ /^over/) {
-		$count and $depth and do_list("over",$all[$i+1],\$in_list,\$depth);
-	    }
-	    elsif ($cmd =~ /^back/) {
-		if ($count) {  # producing html
-		    ($depth) or next; # just skip it
-		    do_list("back",$all[$i+1],\$in_list,\$depth);
-		    do_rest("$title$rest");
-		}
-	    }
-	    elsif ($cmd =~ /^cut/) {
-		next;
-	    }
-            elsif ($cmd =~ /^for/) {  # experimental pragma html
-                if ($count) {  # producing html
-                    if ($title =~ s/^html//) {
-                        $in_html =1;
-                        do_rest("$title$rest");
-                    }
-                }
-            }
-            elsif ($cmd =~ /^begin/) {  # experimental pragma html
-                if ($count) {  # producing html
-                    if ($title =~ s/^html//) {
-                        print HTML $title,"\n",$rest;
-                    }
-                    elsif ($title =~ /^end/) {
-                        next;
-                    }
-                }
-            }
-	    elsif ($Debug{"misc"}) { 
-		warn("unrecognized header: $cmd");
-	    }
-	}
-        # close open lists without '=back' stmts
-	if ($count) {  # producing html
-	    while ($depth) {
-		 do_list("back",$all[$i+1],\$in_list,\$depth);
-	    }
-	    print HTML "\n</BODY>\n</HTML>\n";
-	}
-    }
-}
-print INDEX "\n</UL></BODY>\n</HTML>\n";
-
-sub do_list{   # setup a list type, depending on some grok logic
-    my($which,$next_one,$list_type,$depth) = @_;
-    my($key);
-    if ($which eq "over") {
-	unless ($next_one =~ /^item\s+(.*)/) {
-	    warn "Bad list, $1\n" if $Debug{"misc"};
-	}
-	$key = $1;
-
-	if      ($key =~ /^1\.?/) {
-	    $$list_type = "OL";
-	} elsif ($key =~ /\*\s*$/) {
-	    $$list_type = "UL";
-	} elsif ($key =~ /\*?\s*\w/) {
-	    $$list_type = "DL";
-	} else {
-	    warn "unknown list type for item $key" if $Debug{"misc"};
-	}
-
-	print HTML qq{\n};
-	print HTML qq{<$$list_type>};
-	$$depth++;
-    }
-    elsif ($which eq "back") {
-	print HTML qq{\n</$$list_type>\n};
-	$$depth--;
-    }
-}
-
-sub do_hdr{   # headers
-    my($num,$title,$rest,$depth) = @_;
-    my($savename,$restofname);
-    print HTML qq{<p><hr>\n} if $num == 1;
-    ($savename = $title) =~ s/^(\w+)([\s,]+.*)/$1/;
-    $restofname = $2;
-    (defined($Podnames{$savename})) ? ($savename = $savename) : ($savename = 0);
-    process_thing(\$title,"NAME");
-    print HTML qq{\n<H$num> };
-    if($savename){
-	print HTML "<A HREF=\"$Podnames{$savename}\">$savename$restofname</A>"; 
-    }
-    else{
-        print HTML $title; 
-    }
-    print HTML qq{</H$num>\n};
-    do_rest($rest);
-}
-
-sub do_item{  # list items
-    my($title,$rest,$list_type) = @_;
-    my $bullet_only;
-    $bullet_only = ($title eq '*' and $list_type eq 'UL') ? 1 : 0;
-    my($savename);
-    $savename = $title;
-    (defined($Podnames{$savename})) ? ($savename = $savename) : ($savename = 0);
-    process_thing(\$title,"NAME");
-    if ($list_type eq "DL") {
-	print HTML qq{\n<DT>\n};
-	if($savename){
-	    print HTML "<A HREF=\"$Podnames{$savename}\">$savename $rest</A>\n</DT>"; 
-	}
-
-	else{
-	    (print HTML qq{\n<STRONG>\n}) unless ($title =~ /STRONG/);
-	    print HTML $title; 
-		if($title !~ /STRONG/){
-        	print HTML "\n</STRONG></DT>\n";
-		} else {
-			print HTML "</DT>\n";
-		}
-	}
-	print HTML qq{<DD>\n};
-    }
-    else {
-	print HTML qq{\n<LI>};
-	unless ($bullet_only or $list_type eq "OL") {
-	    if($savename){
-		print HTML "<A HREF=\"$savename.$htmlext\">$savename</A>"; 
-	    }
-	    else{
-		print HTML $title,"\n";
-	    }
-	}
-    }
-    do_rest($rest);
-}
-
-sub do_rest{   # the rest of the chunk handled here
-    my($rest) = @_;
-    my(@lines,$p,$q,$line,,@paras,$inpre);
-    @paras = split(/\n\n\n*/,$rest);  
-    for ($p = 0; $p <= $#paras; $p++) {
-	$paras[$p] =~ s/^\n//mg;
-	@lines = split(/\n/,$paras[$p]);
-        if ($in_html) {  # handle =for html paragraphs
-            print HTML $paras[0];
-            $in_html = 0;
-            next;
-        }
-	elsif ($lines[0] =~ /^\s+\w*\t.*/) {  # listing or unordered list
-	    print HTML qq{<UL>};
-	    foreach $line (@lines) { 
-		($line =~ /^\s+(\w*)\t(.*)/) && (($key,$rem) = ($1,$2));
-		print HTML defined($Podnames{$key}) 
-				?  "<LI>$type$Podnames{$key}\">$key<\/A>\t$rem</LI>\n" 
-				: "<LI>$line</LI>\n";
-	    }
-	    print HTML qq{</UL>\n};
-	}
-	elsif ($lines[0] =~ /^\s/) {       # preformatted code
-	    if ($paras[$p] =~/>>|<</) {
-		print HTML qq{\n<PRE>\n};
-		$inpre=1;
-	    }
-	    else {                         # Still cant beat XMP.  Yes, I know 
-		print HTML qq{\n<XMP>\n};      # it's been obsoleted... suggestions?
-		$inpre = 0;
-	    }
-	    while (defined($paras[$p])) {
-	        @lines = split(/\n/,$paras[$p]);
-		foreach $q (@lines) {      # mind your p's and q's here :-)
-		    if ($paras[$p] =~ />>|<</) {
-			if ($inpre) {
-			    process_thing(\$q,"HTML");
-			}
-			else {
-			    print HTML qq{\n</XMP>\n};
-			    print HTML qq{<PRE>\n};
-			    $inpre=1;
-			    process_thing(\$q,"HTML");
-			}
-		    }
-		    1 while $q =~  s/\t+/' 'x (length($&) * 8 - length($`) % 8)/e;
-		    print HTML  $q,"\n";
-		}
-		last if $paras[$p+1] !~ /^\s/;
-		$p++;
-	    }
-	    print HTML ($inpre==1) ? (qq{\n</PRE>\n}) : (qq{\n</XMP>\n});
-	}
-	else {                             # other text
-	    @lines = split(/\n/,$paras[$p]);
-	    foreach $line (@lines) {
-                process_thing(\$line,"HTML");
-		$line =~ s/STRONG([^>])/STRONG>$1/;  # lame attempt to fix strong
-		print HTML qq{$line\n};
-	    }
-	}
-	print HTML qq{<p>};
-    }
-}
-
-sub process_thing{       # process a chunk, order important
-    my($thing,$htype) = @_;
-    pre_escapes($thing);
-    find_refs($thing,$htype);
-    post_escapes($thing);
-}
-
-sub scan_thing{           # scan a chunk for later references
-    my($cmd,$title,$pod) = @_;
-    $_ = $title;
-    s/\n$//;
-    s/E<(.*?)>/&$1;/g;
-    # remove any formatting information for the headers
-    s/[SFCBI]<(.*?)>/$1/g;         
-    # the "don't format me" thing
-    s/Z<>//g;
-    if ($cmd eq "item") {
-        /^\*/ and  return; 	# skip bullets
-        /^\d+\./ and  return; 	# skip numbers
-        s/(-[a-z]).*/$1/i;
-	trim($_);
-        return if defined $A->{$pod}->{"Items"}->{$_};
-        $A->{$pod}->{"Items"}->{$_} = gensym($pod, $_);
-        $A->{$pod}->{"Items"}->{(split(' ',$_))[0]}=$A->{$pod}->{"Items"}->{$_};
-        Debug("items", "item $_");
-        if (!/^-\w$/ && /([%\$\@\w]+)/ && $1 ne $_ 
-    	    && !defined($A->{$pod}->{"Items"}->{$_}) && ($_ ne $1)) 
-        {
-    	    $A->{$pod}->{"Items"}->{$1} = $A->{$pod}->{"Items"}->{$_};
-    	    Debug("items", "item $1 REF TO $_");
-        } 
-        if ( m{^(tr|y|s|m|q[qwx])/.*[^/]} ) {
-    	    my $pf = $1 . '//';
-    	    $pf .= "/" if $1 eq "tr" || $1 eq "y" || $1 eq "s";
-    	    if ($pf ne $_) {
-    	        $A->{$pod}->{"Items"}->{$pf} = $A->{$pod}->{"Items"}->{$_};
-    	        Debug("items", "item $pf REF TO $_");
-    	    }
-	}
-    }
-    elsif ($cmd =~ /^head[12]/) {                
-        return if defined($A->{$pod}->{"Headers"}->{$_});
-        $A->{$pod}->{"Headers"}->{$_} = gensym($pod, $_);
-        Debug("headers", "header $_");
-    } 
-    else {
-        warn "unrecognized header: $cmd" if $Debug;
-    } 
-}
-
-
-sub picrefs { 
-    my($char, $bigkey, $lilkey,$htype) = @_;
-    my($key,$ref,$podname);
-    for $podname ($pod,@inclusions) {
-	for $ref ( "Items", "Headers" ) {
-	    if (defined $A->{$podname}->{$ref}->{$bigkey}) {
-		$value = $A->{$podname}->{$ref}->{$key = $bigkey};
-		Debug("subs", "bigkey is $bigkey, value is $value\n");
-	    } 
-	    elsif (defined $A->{$podname}->{$ref}->{$lilkey}) {
-		$value = $A->{$podname}->{$ref}->{$key = $lilkey};
-		return "" if $lilkey eq '';
-		Debug("subs", "lilkey is $lilkey, value is $value\n");
-	    } 
-	} 
-	if (length($key)) {
-		($pod2, $num) = $value =~ /^(.*)_(\S+_\d+)$/;
-	    if ($htype eq "NAME") {  
-			return "\n<A NAME=\"".$value."\">\n$bigkey</A>\n"
-	    }
-	    else {
-                1; # break here
-			return "\n$type$Podnames{$pod2}\#".$value."\">$bigkey<\/A>\n";
-	    }
-	} 
-    }
-    if ($char =~ /[IF]/) {
-	return "<EM>$bigkey</EM>";
-    } elsif ($char =~ /C/) {
-		return "<CODE>$bigkey</CODE>";
-    } else {
-		if($bigkey =~ /STRONG/){
-	    	return $bigkey;
-		}
-		else {
-	    	return "<STRONG>$bigkey</STRONG>";
-		}
-    }
-} 
-
-sub find_refs { 
-    my($thing,$htype) = @_;
-    my($orig) = $$thing;
-    # LREF: a manpage(3f) we don't know about
-    for ($$thing) {
-	#s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))>:the I<$1>$2 manpage:g;
-        s@(\S+?://\S*[^.,;!?\s])@noremap(qq{<A HREF="$1">$1</A>})@ge;
-        s,([a-z0-9_.-]+\@([a-z0-9_-]+\.)+([a-z0-9_-]+)),noremap(qq{<A HREF="mailto:$1">$1</A>}),gie;
-	s/L<([^>]*)>/lrefs($1,$htype)/ge;
-	s/([CIBF])<(\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge;
-	s/(S)<([^\/]\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge;
-	s/((\w+)\(\))/picrefs("I", $1, $2,$htype)/ge;
-	s/([\$\@%](?!&[gl]t)([\w:]+|\W\b))/varrefs($1,$htype)/ge;
-    }
-    if ($$thing eq $orig && $htype eq "NAME") { 
-	$$thing = picrefs("I", $$thing, "", $htype);
-    }
-
-}
-
-sub lrefs {
-    my($page, $item) = split(m#/#, $_[0], 2);
-    my($htype) = $_[1];
-    my($podname);
-    my($section) = $page =~ /\((.*)\)/;
-    my $selfref;
-    if ($page =~ /^[A-Z]/ && $item) {
-	$selfref++;
-	$item = "$page/$item";
-	$page = $pod;
-    }  elsif (!$item && $page =~ /[^a-z\-]/ && $page !~ /^\$.$/) {
-	$selfref++;
-	$item = $page;
-	$page = $pod;
-    } 
-    $item =~ s/\(\)$//;
-    if (!$item) {
-    	if (!defined $section && defined $Podnames{$page}) {
-	    return "\n$type$Podnames{$page}\">\nthe <EM>$page</EM> manpage<\/A>\n";
-	} else {
-	    (warn "Bizarre entry $page/$item") if $Debug;
-	    return "the <EM>$_[0]</EM>  manpage\n";
-	} 
-    } 
-
-    if ($item =~ s/"(.*)"/$1/ || ($item =~ /[^\w\/\-]/ && $item !~ /^\$.$/)) {
-	$text = "<EM>$item</EM>";
-	$ref = "Headers";
-    } else {
-	$text = "<EM>$item</EM>";
-	$ref = "Items";
-    } 
-    for $podname ($pod, @inclusions) {
-	undef $value;
-	if ($ref eq "Items") {
-	    if (defined($value = $A->{$podname}->{$ref}->{$item})) {
-			($pod2,$num) = split(/_/,$value,2);  # break here
-			return (($pod eq $pod2) && ($htype eq "NAME"))
-	    		? "\n<A NAME=\"".$value."\">\n$text</A>\n"
-	    		: "\n$type$Podnames{$pod2}\#".$value."\">$text<\/A>\n";
-        }
-    } 
-	elsif ($ref eq "Headers") {
-	    if (defined($value = $A->{$podname}->{$ref}->{$item})) {
-		($pod2,$num) = split(/_/,$value,2); # break here
-		return (($pod eq $pod2) && ($htype eq "NAME")) 
-	    	? "\n<A NAME=\"".$value."\">\n$text</A>\n"
-	    	: "\n$type$Podnames{$pod2}\#".$value."\">$text<\/A>\n";
-            }
-	}
-    }
-    warn "No $ref reference for $item (@_)" if $Debug;
-    return $text;
-} 
-
-sub varrefs {
-    my ($var,$htype) = @_;
-    for $podname ($pod,@inclusions) {
-	if ($value = $A->{$podname}->{"Items"}->{$var}) {
-	    ($pod2,$num) = split(/_/,$value,2);
-	    Debug("vars", "way cool -- var ref on $var");
-	    return (($pod eq $pod2) && ($htype eq "NAME"))  # INHERIT $_, $pod
-		? "\n<A NAME=\"".$value."\">\n$var</A>\n"
-		: "\n$type$Podnames{$pod2}\#".$value."\">$var<\/A>\n";
-	}
-    }
-    Debug( "vars", "bummer, $var not a var");
-    if($var =~ /STRONG/){
-		return $var;
-    }
-    else{
-		return "<STRONG>$var</STRONG>";
-    }
-} 
-
-sub gensym {
-    my ($podname, $key) = @_;
-    $key =~ s/\s.*//;
-    ($key = lc($key)) =~ tr/a-z/_/cs;
-    my $name = "${podname}_${key}_0";
-    $name =~ s/__/_/g;
-    while ($sawsym{$name}++) {
-        $name =~ s/_?(\d+)$/'_' . ($1 + 1)/e;
-    }
-    return $name;
-} 
-
-sub pre_escapes {  # twiddle these, and stay up late  :-)
-    my($thing) = @_;
-    for ($$thing) { 
-		s/([\200-\377])/noremap("&#".ord($1).";")/ge;
-		s/"(.*?)"/``$1''/gs;
-		s/&/noremap("&amp;")/ge;
-		s/<</noremap("&lt;&lt;")/eg;
-		s/([^ESIBLCF])</$1\&lt\;/g;
-		s/E<(\d+)>/\&#$1\;/g;                     # embedded numeric special
-		s/E<([^\/][^<>]*)>/\&$1\;/g;              # embedded special
-    }
-}
-sub noremap {   # adding translator for hibit chars soon
-    my $hide = $_[0];
-    $hide =~ tr/\000-\177/\200-\377/;  
-    $hide;
-} 
-
-
-sub post_escapes {
-    my($thing) = @_;
-    for ($$thing) {
-	s/([^GM])>>/$1\&gt\;\&gt\;/g;
-	s/([^D][^"MGA])>/$1\&gt\;/g;
-	tr/\200-\377/\000-\177/;
-    }
-}
-
-sub Debug {
-    my $level = shift;
-    print STDERR @_,"\n" if $Debug{$level};
-} 
-
-sub dumptable  {
-    my $t = shift;
-    print STDERR "TABLE DUMP $t\n";
-    foreach $k (sort keys %$t) {
-	printf STDERR "%-20s <%s>\n", $t->{$k}, $k;
-    } 
-} 
-sub trim {
-    for (@_) {
-        s/^\s+//;
-        s/\s\n?$//;
-    }
-}
-sub wanted {
-    my $name = $name;
-    if (-f $_) {
-        if ($name =~ /\.p(m|od)$/){
-            push(@modpods, $name) if ($name =~ /\.p(m|od)$/);
-	}
-    }
-}
+=head1 NAME
 
+pod2html - convert .pod files to .html files
+
+=head1 SYNOPSIS
+
+    pod2html --help --htmlroot=<name> --infile=<name> --outfile=<name>
+             --podpath=<name>:...:<name> --podroot=<name>
+             --libpods=<name>:...:<name> --recurse --norecurse --verbose
+             --index --noindex --title=<name>
+
+=head1 DESCRIPTION
+
+Converts files from pod format (see L<perlpod>) to HTML format.
+
+=head1 ARGUMENTS
+
+pod2html takes the following arguments:
+
+=over 4
+
+=item help
+
+  --help
+
+Displays the usage message.
+
+=item htmlroot
+
+  --htmlroot=name
+
+Sets the base URL for the HTML files.  When cross-references are made,
+the HTML root is prepended to the URL.
+
+=item infile
+
+  --infile=name
+
+Specify the pod file to convert.  Input is taken from STDIN if no
+infile is specified.
+
+=item outfile
+
+  --outfile=name
+
+Specify the HTML file to create.  Output goes to STDOUT if no outfile
+is specified.
+
+=item podroot
+
+  --podroot=name
+
+Specify the base directory for finding library pods.
+
+=item podpath
+
+  --podpath=name:...:name
+
+Specify which subdirectories of the podroot contain pod files whose
+HTML converted forms can be linked-to in cross-references.
+
+=item libpods
+
+  --libpods=name:...:name
+
+List of page names (eg, "perlfunc") which contain linkable C<=item>s.
+
+=item netscape
+
+  --netscape
+
+Use Netscape HTML directives when applicable.
+
+=item nonetscape
+
+  --nonetscape
+
+Do not use Netscape HTML directives (default).
+
+=item index
+
+  --index
+
+Generate an index at the top of the HTML file (default behaviour).
+
+=item noindex
+
+  --noindex
+
+Do not generate an index at the top of the HTML file.
+
+
+=item recurse
+
+  --recurse
+
+Recurse into subdirectories specified in podpath (default behaviour).
+
+=item norecurse
+
+  --norecurse
+
+Do not recurse into subdirectories specified in podpath.
+
+=item title
+
+  --title=title
+
+Specify the title of the resulting HTML file.
+
+=item verbose
+
+  --verbose
+
+Display progress messages.
+
+=back
+
+=head1 AUTHOR
+
+Tom Christiansen, E<lt>tchrist@perl.comE<gt>.
+
+=head1 BUGS
+
+See L<Pod::Html> for a list of known bugs in the translator.
+
+=head1 SEE ALSO
+
+L<perlpod>, L<Pod::HTML>
+
+=head1 COPYRIGHT
+
+This program is distributed under the Artistic License.
+
+=cut
+
+use Pod::Html;
+
+pod2html @ARGV;
 !NO!SUBS!
 
 close OUT or die "Can't close $file: $!";