[he@NetBSD.org: pkg/48640: Many lang/tcl man pages fail to render correctly]

[he@NetBSD.org: pkg/48640: Many lang/tcl man pages fail to render correctly]

[Thomas Klausner]

FYI: A bug report was filed in NetBSD against an older mandoc version
in connection with tcl man pages.

I haven't yet tried if the current mandoc fares better.
 Thomas

P.S.: Yes, I know, I still have to reply about the utf-8 issue. Sorry
for the delay.

----- Forwarded message from he@NetBSD.org -----

Date: Wed,  5 Mar 2014 10:10:00 +0000 (UTC)
From: he@NetBSD.org
To: pkg-manager@netbsd.org, gnats-admin@netbsd.org, pkgsrc-bugs@netbsd.org
Subject: pkg/48640: Many lang/tcl man pages fail to render correctly

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


----- End forwarded message -----
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: [he@NetBSD.org: pkg/48640: Many lang/tcl man pages fail to render correctly]

[Ingo Schwarze]

Hi Thomas,

Thomas Klausner wrote on Wed, Mar 05, 2014 at 10:27:43PM +0100:

> FYI: A bug report was filed in NetBSD against an older mandoc version
> in connection with tcl man pages.

Ouch.  Starting to investigate, i immediately see multiple issues
popping up.  This is going to lead to a whole serious of commits,
probably.

On top of that, that manual is using lots of low-level roff stuff,
not all of which is implemented in mandoc(1), in particular
 - number register arithmetics,
 - width measurements,
 - complex conditional criteria,
 - tabulator settings

So even if this leads to multiple bug fixes, i'm not yet sure
all the missing features will get implemented.  It's not
completely out of the question, though.  It might be possible
to fix this completely, or it might cause too much work for now.

> I haven't yet tried if the current mandoc fares better.

Slightly, but the output still isn't OK.

> P.S.: Yes, I know, I still have to reply about the utf-8 issue.
> Sorry for the delay.

Meanwhile, i have taken one step forward, fixing rendering of accents
in -Tutf8 to be non-combining, fixing some of the issues that a
switch of the default would have raised.  More feedback is welcome,
though.

Yours,
  Ingo

> .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
> .\}
> .\}
> ..
> .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
> ..

Wow.  Calling that man(7) is, well, a bold claim.  :-/
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: [he@NetBSD.org: pkg/48640: Many lang/tcl man pages fail to render correctly]

[Ingo Schwarze]

Hi,

Ingo Schwarze wrote on Thu, Mar 06, 2014 at 06:06:27PM +0100:
> Thomas Klausner wrote on Wed, Mar 05, 2014 at 10:27:43PM +0100:

>> FYI: A bug report was filed in NetBSD against an older mandoc version
>> in connection with tcl man pages.

[...]
> So even if this leads to multiple bug fixes, i'm not yet sure
> all the missing features will get implemented.  It's not
> completely out of the question, though.  It might be possible
> to fix this completely, or it might cause too much work for now.

I have implemented the critical features for this page such that
all the content is shown nicely, see

  http://gnats.netbsd.org/cgi-bin/query-pr-single.pl?number=48640

and added the remaining tasks, being both non-critical and too
much work at this point, to the TODO list:

  http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml#rev1.167

Just FYI.

Thanks for reporting,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv