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

[Russ Allbery]

Vincent Fourmond <fourmond at debian.org> writes:

>   Looking at those manual pages, it appears that they are broken, see:
>
> [...]
>
> .SH "NAME"
> PDF::API2::Outline \- outline management
> .ie n .SH "$otl = PDF::API2::Outline\->new $api,$parent,$prev"
>     ^ ^^^
>     1 2
>
> 1 should not be here
> 2 should be at the beginning of a line.

However, the .ie n is necessary; it is selecting between nroff and groff
to choose how to format that heading.  The complete excerpt of code is:

.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"

In other words, there are two versions of that section heading depending
on which processor you're using.

I think there are two bugs here.  First, the POD documentation does not
follow the recommended structure in the pod2man man page and instead puts
API calls as first-level headings.  If it weren't doing that, you wouldn't
see this problem.  In my opinion, there should be a =head1 METHODS and
then each method should be an =item, not a =head1.

Second, I think there's a bug in man, namely that when searching for the
NAME section, it's not stopping that search at the .ie n .SH construct.  I
understand why that's happening, but I still think that it should be smart
enough to figure out that there's an .SH there via either branch of the
.ie (or, failing that, just stop parsing the NAME section at the first
nroff command, since the NAME section should not include nroff commands
anyway).

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