pod2man generated .IX lines upset whatis on Solaris

Subject: Re: Perl generates incorrect manpages

John Redford wrote
> Perl is generating manpages which contain lines like:

> .SH "NAME"
> .IX Header "NAME"
> perlbot \- Bag'o Object Tricks (the BOT)
>
> Which on Solaris at least causes the manpage index to think that '.IX'
> 'header' and '"NAME"' are all manpages.

There was a thread about this about two weeks ago under the subject
"Re: pod2man .IX question (for Solaris bug fix)".   Kurt Starsinic
posted a patch which didn't get into the 5.004_02 release, probably because
it appears to be incorrect (see below).

>                                         This is trivially fixed by
> moving the .IX to before the .SH:
>
> .IX Header "NAME"
> .SH "NAME"
> perlbot \- Bag'o Object Tricks (the BOT)

It may need something more complicated, since Kurt wrote
:I would like to keep them, if possible, but moving them down a line or two
:doesn't solve the problem.  Following is a patch which moves all of the .IX
:lines to the end of the man page, which (I believe) will appease all
:interested parties.  This patch DTRT under Solaris 2.5.1/SPARC and OSF1
:V4.0/DEC Alpha, both running perl 5.004 (no patches):

I doubt this last assertion, since I noted a couple of suspicious looking
bits in the patch (in a subsequent message in the above thread).   This
is perhaps why Tim didn't include it in 5.004_02.   (Also, the patch
was for pod2man rather than pod2man.PL.)

I attach below Kurt's patch with my corrections.   I've checked that this
doesn't actually wreck pod2man totally, but I can't test it further since
i)   I don't know what the .IX is meant to do.
ii)  I don't actually know what the code is meant to be doing.
iii) I don't have a suitable Solaris (etc) system to try on.

Perhaps someone else could take this further.

Credited: John Redford <jmr@whirlwind.fmr.com>
Credited: Kurt Starsinic <kstar@isinet.com>

p5p-msgid: E0wxoUZ-0006Ee-00@ursa.cus.cam.ac.uk

diff --git a/pod/pod2man.PL b/pod/pod2man.PL
index 79e3edd..46f47a8 100644 (file)
--- a/pod/pod2man.PL
+++ b/pod/pod2man.PL
@@ -310,6 +310,7 @@ Tom Christiansen such that Larry probably doesn't recognize it anymore.
 
 $/ = "";
 $cutting = 1;
+@Indices = ();
 
 # We try first to get the version number from a local binary, in case we're
 # running an installed version of Perl to produce documentation from an
@@ -555,13 +556,14 @@ END
 
 print <<"END";
 .TH $name $section "$RP" "$date" "$center"
-.IX Title "$name $section"
 .UC
 END
 
+push(@Indices, qq{.IX Title "$name $section"});
+
 while (($name, $desc) = each %namedesc) {
     for ($name, $desc) { s/^\s+//; s/\s+$//; }
-    print qq(.IX Name "$name - $desc"\n);
+    push(@Indices, qq(.IX Name "$name - $desc"\n));
 }
 
 print <<'END';
@@ -883,11 +885,11 @@ while (<>) {
            s/\s+$//;
            delete $wanna_see{$_} if exists $wanna_see{$_};
            print qq{.SH "$_"\n};
-           print qq{.IX Header "$_"\n};
+      push(@Indices, qq{.IX Header "$_"\n});
        }
        elsif ($Cmd eq 'head2') {
            print qq{.Sh "$_"\n};
-           print qq{.IX Subsection "$_"\n};
+      push(@Indices, qq{.IX Subsection "$_"\n});
        }
        elsif ($Cmd eq 'over') {
            push(@indent,$indent);
@@ -906,7 +908,7 @@ while (<>) {
            s/[^"]""([^"]+?)""[^"]/'$1'/g;
            # here do something about the $" in perlvar?
            print STDOUT qq{.Ip "$_" $indent\n};
-           print qq{.IX Item "$_"\n};
+      push(@Indices, qq{.IX Item "$_"\n});
        }
        elsif ($Cmd eq 'pod') {
            # this is just a comment
@@ -939,6 +941,8 @@ if (%wanna_see && !$lax) {
     $oops++;
 }
 
+foreach (@Indices) { print "$_\n"; }
+
 exit;
 #exit ($oops != 0);
 
@@ -1042,7 +1046,7 @@ sub makespace {
 sub mkindex {
     my ($entry) = @_;
     my @entries = split m:\s*/\s*:, $entry;
-    print ".IX Xref ";
+    push @Indices, ".IX Xref " . join ' ', map {qq("$_")} @entries;
     for $entry (@entries) {
        print qq("$entry" );
     }