Bug#467444: libpdf-api2-perl: PDF::API2::Outline.3pm and PDF::API2::Page.3pm are broken
tags 467476 fixed-upstream thanks On Mon, Feb 25, 2008 at 11:11:51AM -0800, Russ Allbery wrote: 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: [...] 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. In theory I agree that lexgrog should parse conditionals and try both branches. In practice I suspect doing that in lex will be horrifically painful! I've gone for the second option, and just made it terminate whatis parsing at conditionals: Thu Feb 28 10:47:22 GMT 2008 Colin Watson [EMAIL PROTECTED] * src/lexgrog.l: Terminate MAN_NAME at .ie or .if conditionals (Debian bug #467444). Thanks, -- Colin Watson [EMAIL PROTECTED] -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#467476: Bug#467444: libpdf-api2-perl: PDF::API2::Outline.3pm and PDF::API2::Page.3pm are broken
Colin Watson [EMAIL PROTECTED] writes: In theory I agree that lexgrog should parse conditionals and try both branches. In practice I suspect doing that in lex will be horrifically painful! I've gone for the second option, and just made it terminate whatis parsing at conditionals: Thu Feb 28 10:47:22 GMT 2008 Colin Watson [EMAIL PROTECTED] * src/lexgrog.l: Terminate MAN_NAME at .ie or .if conditionals (Debian bug #467444). Thanks, Colin! -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#467444: libpdf-api2-perl: PDF::API2::Outline.3pm and PDF::API2::Page.3pm are broken
Package: libpdf-api2-perl Version: 0.69-1 Severity: minor Hello, 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. 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. It is likely that the other manual pages are also broken this way: for instance: ~ whatis PDF::API2::Resource PDF::API2::Resource (3pm) - - generic PDF::API2 resource class n .SH $res = PDF::API2::Resource-new $pdf,... They only don't trigger the problem because their text is less long. I'm unsure whether this is a bug in the structure of the original pages or if it is a pod2man problem. Regards, Vincent Fourmond -- System Information: Debian Release: lenny/sid APT prefers unstable APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable') Architecture: amd64 (x86_64) Kernel: Linux 2.6.24-1-amd64 (SMP w/2 CPU cores) Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash Versions of packages libpdf-api2-perl depends on: ii libcompress-zlib-perl 2.008-1Perl module for creation and manip ii perl 5.8.8-12 Larry Wall's Practical Extraction ii ttf-dejavu2.23-1 Metapackage to pull in ttf-dejavu- libpdf-api2-perl recommends no packages. -- no debconf information -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#467444: libpdf-api2-perl: PDF::API2::Outline.3pm and PDF::API2::Page.3pm are broken
clone 467444 -1
retitle -1 whatis parsing confused by .ie
reassign -1 man-db
thanks
Vincent Fourmond [EMAIL PROTECTED] 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 ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#467444: libpdf-api2-perl: PDF::API2::Outline.3pm and PDF::API2::Page.3pm are broken
Vincent Fourmond [EMAIL PROTECTED] 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 ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
