Bug#467444: libpdf-api2-perl: PDF::API2::Outline.3pm and PDF::API2::Page.3pm are broken

[Russ Allbery]

clone 467444 -1
retitle -1 whatis parsing confused by .ie
reassign -1 man-db
thanks

Vincent Fourmond <fourmond at debian.org> writes:

>   mandb's crontab complains thus:
>
> /etc/cron.daily/man-db:
> /usr/bin/mandb: warning: whatis for PDF::API2::Page.3pm.gz exceeds 2048 bytes, truncating.
> /usr/bin/mandb: warning: whatis for PDF::API2::Outline.3pm.gz exceeds 2048 bytes, truncating.

Hi Colin,

This is a case where I think that man-db's whatis parsing is
insufficiently smart.  pod2man generates an .ie construct for some .SH
headings because of a Solaris nroff bug, specifically:

        # Work around the Solaris nroff bug where \f(CW\fP leaves the font set
        # to Roman rather than the actual previous font when used in headings.
        # troff output may still be broken, but at least we can fix nroff by
        # just switching the font changes to the non-fixed versions.
        $nroff =~ s/\Q$$self{FONTS}{100}\E(.*)\\f[PR]/$1/g;
        $nroff =~ s/\Q$$self{FONTS}{101}\E(.*)\\f([PR])/\\fI$1\\f$2/g;
        $nroff =~ s/\Q$$self{FONTS}{110}\E(.*)\\f([PR])/\\fB$1\\f$2/g;
        $nroff =~ s/\Q$$self{FONTS}{111}\E(.*)\\f([PR])/\\f\(BI$1\\f$2/g;

        # Now finally output the command.  Bother with .ie only if the nroff
        # and troff output aren't the same.
        if ($nroff ne $troff) {
            return ".ie n $command $nroff\n.el $command $troff\n";
        } else {
            return "$command $nroff\n";
        }

The result is that the start of these man pages looks like:

.SH "NAME"
PDF::API2::Page \- page management
.ie n .SH "$page\fP = PDF::API2::Page\->new \f(CW$pdf\fP, \f(CW$parent\fP, \f(CW$index"
.el .SH "\f(CW$page\fP = PDF::API2::Page\->new \f(CW$pdf\fP, \f(CW$parent\fP, \f(CW$index\fP"

However, man-db's whatis parsing is confused by this construct.

Ideally, I think it should be made intelligent enough to recognize .ie and
realize that there's an .SH there along either branch of the conditional,
and therefore the NAME section is ended.  Failing that, I think it would
make sense to terminate whatis parsing at the first nroff directive (line
starting with .) after the .SH NAME, given that in practice nroff
directives don't work inside NAME sections anyway.

Let me know what you think.

-- 
Russ Allbery (rra at debian.org)               <http://www.eyrie.org/~eagle/>