[perl #107870] installhtml no longer generates perlfunc.html

# New Ticket Created by  Nicholas Clark 
# Please include the string:  [perl #107870]
# in the subject line of all future correspondence about this issue. 
# <URL: https://rt.perl.org:443/rt3/Ticket/Display.html?id=107870 >


Backstory. I didn't know *any* of this before this morning. I'm not the
expert. I just get paid to get my hands dirty figuring this madness out:


./installhtml splits perlfunc.pod into a subdirectory perlfunc/ containing
one HTML file per function, and generates an index into this for
perlfunc.html

Only, as of now in blead it no longer does:

$ cat /home/nick/Sandpit/snap-v5.15.6-449-gc3c3303/lib/perl5/5.15.6/html/pod/perlfunc.html
<DL COMPACT>
</DL>


It's suppose to look something like this:

$ head /home/nick/Sandpit/snap-v5.14.0/lib/perl5/5.14.0/html/pod/perlfunc.html
<DL COMPACT>
<DT><A HREF="perlfunc/X.html"><p>-X</A></DT><DD>a file test (-r, -x, etc)</p></DD>
<DT><A HREF="perlfunc/abs.html"><p>abs</A></DT><DD>absolute value function</p></DD>
<DT><A HREF="perlfunc/accept.html"><p>accept</A></DT><DD>accept an incoming socket connect</p></DD>
<DT><A HREF="perlfunc/alarm.html"><p>alarm</A></DT><DD>schedule a SIGALRM</p></DD>
<DT><A HREF="perlfunc/atan2.html"><p>atan2</A></DT><DD>arctangent of Y/X in the range -PI to PI</p></DD>
<DT><A HREF="perlfunc/bind.html"><p>bind</A></DT><DD>binds an address to a socket</p></DD>
<DT><A HREF="perlfunc/binmode.html"><p>binmode</A></DT><DD>prepare binary files for I/O</p></DD>
<DT><A HREF="perlfunc/bless.html"><p>bless</A></DT><DD>create an object</p></DD>
<DT><A HREF="perlfunc/caller.html"><p>caller</A></DT><DD>get context of the current subroutine call</p></DD>


It's generated by create_index() in ./installhtml, which opens each HTML file
in turn and searches them:

    # 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);


Only, as of now in blead $name is undef, and ./installhtml generates a lot of
these diagnostics at the end of its run:

Use of uninitialized value $name in pattern match (m//) at installhtml line 321.


This is due to the regex above not matching. The code is expecting HTML like
this:

<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>abs - absolute value function</p>
<p>

whereas its now of this form

<h1 id="NAME">NAME</h1>

<p>abs - absolute value function</p>


The fix *may* be simple. Gotchas to look out for are that installhtml
is reading in paragraph mode for no obvious reason. (The old* HTML doesn't
have line feeds structured to structure it into meaningful paragraphs. The
new HTML has lots of linefeeds.


Whilst in the area of fixing that subroutine, one has to ask why it has a
bare unconditional

	next;

with code following it. That's dead code. It's been there since the first
commit. *And* it's had subsequent commits correct it. WTF?

Nicholas Clark

* "old" as in perl 5.14.0 era. installhtml dates to perl-5.003_95,
  commit 54310121b4429747, March 1997.

• [perl #107870] installhtml no longer generates perlfunc.html by Nicholas Clark