NetBSD Problem Report #48640
From he@smistad.uninett.no Wed Mar 5 10:08:44 2014
Return-Path: <he@smistad.uninett.no>
Received: from mail.netbsd.org (mail.netbsd.org [149.20.53.66])
(using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits))
(Client CN "mail.netbsd.org", Issuer "Postmaster NetBSD.org" (verified OK))
by mollari.NetBSD.org (Postfix) with ESMTPS id 584C3A66BF
for <gnats-bugs@gnats.NetBSD.org>; Wed, 5 Mar 2014 09:34:01 +0000 (UTC)
Message-Id: <20140305093354.9C8683D0B4@smistad.uninett.no>
Date: Wed, 5 Mar 2014 10:33:54 +0100 (CET)
From: he@NetBSD.org
Reply-To: he@NetBSD.org
To: gnats-bugs@gnats.NetBSD.org
Subject: Many lang/tcl man pages fail to render correctly
X-Send-Pr-Version: 3.95
>Number: 48640
>Category: pkg
>Synopsis: Many lang/tcl man pages fail to render correctly
>Confidential: no
>Severity: serious
>Priority: medium
>Responsible: pkg-manager
>State: open
>Class: sw-bug
>Submitter-Id: net
>Arrival-Date: Wed Mar 05 10:10:00 +0000 2014
>Last-Modified: Wed Mar 19 18:25:00 +0000 2014
>Originator: Havard Eidnes
>Release: NetBSD 6.1
>Organization:
I try...
>Environment:
System: NetBSD smistad.uninett.no 6.1 NetBSD 6.1 (MAANEN) #1: Mon Jul 1 14:33:56 CEST 2013 he@smistad.uninett.no:/usr/obj/sys/arch/i386/compile/MAANEN i386
Architecture: i386
Machine: i386
>Description:
This applies to both tcl 8.5 and 8.6 from pkgsrc.
Many of the Tcl man pages fail to rencer correctly, at least
with the groff installed on my system. I'm not enough of an
nroff hacker to comprehend what actually goes wrong, but it
appears that some of the macros the Tcl man pages define
themselves fail to work as intended. Example from
"man Tcl_NewStringObj" output:
ARGUMENTS
Points to the first byte of an array of UTF-8-encoded
bytes used to set or append to a string object. [...]
However, the man page source has
.SH ARGUMENTS
.AS "const Tcl_UniChar" *appendObjPtr in/out
.AP "const char" *bytes in
Points to the first byte of an array of UTF-8-encoded bytes
used to set or append to a string object.
.AS and .AP are defined earlier in the Tcl_NewStringObj.3 file:
.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\" # BS - start boxed text
.\" # ^y = starting y location
.\" # ^b = 1
(That also includes one use, if I understand correctly.)
Can some nroff-knowledgeable person please step up to untangle
this line noise and/or explain what needs to be done to make
this work as intended?
>How-To-Repeat:
Do "man Tcl_NewStringObj", watch the confusing doc when parts
are missing.
>Fix:
Sorry, don't know; not sufficient nroff clue.
>Audit-Trail:
From: "Kai-Uwe Eckhardt" <kuehro@gmx.de>
To: gnats-bugs@netbsd.org
Cc:
Subject: Re: pkg/48640: Many lang/tcl man pages fail to render correctly
Date: Wed, 5 Mar 2014 22:24:36 +0100
nroff -man /usr/pkg/man/man3/Tcl_NewStringObj.3 works as expected, but
the same with mandoc -man doesn't.
From: Ingo Schwarze <schwarze@usta.de>
To: gnats-bugs@netbsd.org
Cc: Havard Eidnes <he@netbsd.org>, Thomas Klausner <wiz@netbsd.org>,
Kai-Uwe Eckhardt <kuehro@gmx.de>
Subject: Re: pkg/48640: Many lang/tcl man pages fail to render correctly
Date: Sat, 8 Mar 2014 22:35:05 +0100
Hi Havard and Thomas,
thanks for reporting this issue with Tcl_NewStringObj(3).
That page is using many low-level roff(7) requests and escapes,
so it is challenging for mandoc(1). Some roff features used
by the page are simply not implemented in mandoc because they
don't usually occur in man pages.
Anyway, i have implemented a few new features and fixed several
bugs to let this page render better:
* In the roff parser, implement string comparison conditionals
for the .if and .ie requests.
* In the roff parser, support negation of non-numeric conditionals
for the .if and .ie requests.
* In the roff parser, fix six bugs related to the closing
of conditional blocks on macro lines.
* In the man(7) formatter, fix three bugs related to same-line
detection in .TP head arguments and in .nf text content.
I have committed the following nine patches to the upstream
mandoc CVS repo:
http://mdocml.bsd.lv/cgi-bin/cvsweb/roff.c?cvsroot=mdocml 1.195-198
http://mdocml.bsd.lv/cgi-bin/cvsweb/roff.7?cvsroot=mdocml 1.48
http://mdocml.bsd.lv/cgi-bin/cvsweb/man_term.c?cvsroot=mdocml 1.141-142
http://mdocml.bsd.lv/cgi-bin/cvsweb/man_html.c?cvsroot=mdocml 1.91
http://mdocml.bsd.lv/cgi-bin/cvsweb/tree.c?cvsroot=mdocml 1.51
With these patches, mandoc no longer loses part of the content, but
displays everything in a very readable form. The output from mandoc
still differs from groff output because the page uses some more
features that mandoc doesn't implement (arithmetic calculations in
assignments to number registers, width measurements, and redefinitions
of tabulator positions). Incidentally, the mandoc output even looks
better now than the groff output, even though the groff output
follows more closely what the formatting instructions say. Part
of the groff output is crowded very uglily into a narrow column on
the far right of the terminal, which is not likely to be what the
author intended; there must be some oversight in the macros doing
the width calculations on the author's part, at least regarding the
terminal output case.
Feel free to contact me directly or via <discuss@mdocml.bsd.lv>
for any feedback or questions, or if you would like to see a
public mandoc-1.12.4 release including these patches such that
you can more easily update your system.
Yours,
Ingo
From: Thomas Klausner <wiz@netbsd.org>
To: Ingo Schwarze <schwarze@usta.de>
Cc: gnats-bugs@netbsd.org, Havard Eidnes <he@netbsd.org>,
Kai-Uwe Eckhardt <kuehro@gmx.de>
Subject: Re: pkg/48640: Many lang/tcl man pages fail to render correctly
Date: Wed, 19 Mar 2014 19:23:05 +0100
Hi Ingo!
On Sat, Mar 08, 2014 at 10:35:05PM +0100, Ingo Schwarze wrote:
> With these patches, mandoc no longer loses part of the content, but
> displays everything in a very readable form. The output from mandoc
> still differs from groff output because the page uses some more
> features that mandoc doesn't implement (arithmetic calculations in
> assignments to number registers, width measurements, and redefinitions
> of tabulator positions). Incidentally, the mandoc output even looks
> better now than the groff output, even though the groff output
> follows more closely what the formatting instructions say. Part
> of the groff output is crowded very uglily into a narrow column on
> the far right of the terminal, which is not likely to be what the
> author intended; there must be some oversight in the macros doing
> the width calculations on the author's part, at least regarding the
> terminal output case.
>
> Feel free to contact me directly or via <discuss@mdocml.bsd.lv>
> for any feedback or questions, or if you would like to see a
> public mandoc-1.12.4 release including these patches such that
> you can more easily update your system.
If it's not asking too much, I'd like to see such a release.
Thanks,
Thomas
(Contact us)
$NetBSD: query-full-pr,v 1.39 2013/11/01 18:47:49 spz Exp $
$NetBSD: gnats_config.sh,v 1.8 2006/05/07 09:23:38 tsutsui Exp $
Copyright © 1994-2007
The NetBSD Foundation, Inc. ALL RIGHTS RESERVED.