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

NetBSD Home
NetBSD PR Database Search

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