pkg/48640: Many lang/tcl man pages fail to render correctly

[he%NetBSD.org@localhost]

>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
>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@localhost:/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.