From phk@critter.freebsd.dk  Wed Oct  6 06:57:24 2004
Return-Path: <phk@critter.freebsd.dk>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id BBD9516A4D2
	for <FreeBSD-gnats-submit@freebsd.org>; Wed,  6 Oct 2004 06:57:24 +0000 (GMT)
Received: from critter.freebsd.dk (f170.freebsd.dk [212.242.86.170])
	by mx1.FreeBSD.org (Postfix) with ESMTP id D130043D2F
	for <FreeBSD-gnats-submit@freebsd.org>; Wed,  6 Oct 2004 06:57:23 +0000 (GMT)
	(envelope-from phk@critter.freebsd.dk)
Received: from critter.freebsd.dk (localhost [127.0.0.1])
	by critter.freebsd.dk (8.13.1/8.13.1) with ESMTP id i966vM11009331
	for <FreeBSD-gnats-submit@freebsd.org>; Wed, 6 Oct 2004 08:57:22 +0200 (CEST)
	(envelope-from phk@critter.freebsd.dk)
Received: (from phk@localhost)
	by critter.freebsd.dk (8.13.1/8.13.1/Submit) id i966vLgO009330;
	Wed, 6 Oct 2004 08:57:21 +0200 (CEST)
	(envelope-from phk)
Message-Id: <200410060657.i966vLgO009330@critter.freebsd.dk>
Date: Wed, 6 Oct 2004 08:57:21 +0200 (CEST)
From: Poul-Henning Kamp <phk@critter.freebsd.dk>
Reply-To: Poul-Henning Kamp <phk@critter.freebsd.dk>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: prototype error in signal(3)
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         72375
>Category:       docs
>Synopsis:       prototype error in signal(3)
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    ru
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Oct 06 07:00:47 GMT 2004
>Closed-Date:    Thu Dec 23 02:51:32 GMT 2004
>Last-Modified:  Thu Dec 23 02:51:32 GMT 2004
>Originator:     Poul-Henning Kamp
>Release:        FreeBSD 6.0-CURRENT i386
>Organization:
>Environment:
System: FreeBSD critter.freebsd.dk 6.0-CURRENT FreeBSD 6.0-CURRENT #28: Tue Oct 5 13:21:14 CEST 2004 root@critter.freebsd.dk:/freebsd/src/sys/i386/compile/CRITTER i386


>Description:

	The prototype in signal(3) is misformatted somehow, but I don't
	have enough mdoc clue to fix it:

	    void (*
	     signal(int sig, void (*func)(int)))(int);


>How-To-Repeat:

>Fix:


>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Poul-Henning Kamp <phk@critter.freebsd.dk>
Cc: bug-followup@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Wed, 6 Oct 2004 11:53:41 +0300

 On 2004-10-06 08:57, Poul-Henning Kamp <phk@critter.freebsd.dk> wrote:
 > The prototype in signal(3) is misformatted somehow, but I don't
 > have enough mdoc clue to fix it:
 >
 >     void (*
 >     signal(int sig, void (*func)(int)))(int);
 
 Ruslan has added a comment above the mdoc source of signal.3 that reads
 like this:
 
      45 .\" The following is Quite Ugly, but syntactically correct.
      46 .\" Don't try to
      47 .\" fix it.
      48 .Ft void \*(lp*
      49 .Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
 
 If Ruslan doesn't know of a better way to write this in mdoc, it's quite
 possible that there is none.  One way to write the prototype without
 this strange output is with a typedef, as shown a few lines below in the
 same manpage ;-)
 

From: Joseph Koshy <joseph.koshy@gmail.com>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Wed, 6 Oct 2004 16:53:44 +0530

 Suggested fix.
 
 koshy:anor% cvs diff signal.3                                         
                                                                       
                                                 /usr/src/lib/libc/gen
 Index: signal.3
 ===================================================================
 RCS file: /cvs/FreeBSD/src/lib/libc/gen/signal.3,v
 retrieving revision 1.38
 diff -u -r1.38 signal.3
 --- signal.3    3 Jul 2004 22:30:08 -0000       1.38
 +++ signal.3    6 Oct 2004 11:21:03 -0000
 @@ -45,7 +45,7 @@
  .\" The following is Quite Ugly, but syntactically correct.
  .\" Don't try to
  .\" fix it.
 -.Ft void \*(lp*
 +.Ft void \*(lp*\*(rp
  .Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
  .Pp
  or in

From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: Joseph Koshy <joseph.koshy@gmail.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Wed, 6 Oct 2004 14:36:36 +0300

 On 2004-10-06 16:53, Joseph Koshy <joseph.koshy@gmail.com> wrote:
 > Suggested fix.
 >
 >  .\" The following is Quite Ugly, but syntactically correct.
 >  .\" Don't try to
 >  .\" fix it.
 > -.Ft void \*(lp*
 > +.Ft void \*(lp*\*(rp
 >  .Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
 
 Err, please no.  The type of the return value of signal() is not really
 `void (*)' but something more like:
 
         void (*)(int)
 
 But this is not so easy to separate from the name of the signal()
 function without a typedef; at least not without breaking the validity
 of the C declaration, which is a bad thing since then manpage readers
 cannot copy/paste the prototype of signal() from its manpage.
 

From: Joseph Koshy <joseph.koshy@gmail.com>
To: Giorgos Keramidas <keramida@ceid.upatras.gr>
Cc: bug-followup@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Wed, 6 Oct 2004 14:18:10 +0000

 > Err, please no.  The type of the return value of signal() is not really
 > `void (*)' but something more like:
 > 
 >         void (*)(int)
 
 Yes, my bad.  Please ignore the previous misguided patch.
 
 > But this is not so easy to separate from the name of the signal()
 > function without a typedef; at least not without breaking the validity
 > of the C declaration, which is a bad thing since then manpage readers
 > cannot copy/paste the prototype of signal() from its manpage.
 
 Well the visual ugliness in the current manual page arises from the 
 fact that the .Ft macro forces a line break after its idea of the 
 "type" of the function.
 
 Using .Xo/.Xc suppresses this, and puts the whole declaration on
 one line.
 
 I don't know how to suppress the inter-argument spaces inserted by
 ".Ft".  There is probably still scope for improvement of the patch
 below.
 
 Index: signal.3
 ===================================================================
 RCS file: /cvs/FreeBSD/src/lib/libc/gen/signal.3,v
 retrieving revision 1.38
 diff -u -u -r1.38 signal.3
 --- signal.3    3 Jul 2004 22:30:08 -0000       1.38
 +++ signal.3    6 Oct 2004 19:49:41 -0000
 @@ -45,8 +45,9 @@
  .\" The following is Quite Ugly, but syntactically correct.
  .\" Don't try to
  .\" fix it.
 -.Ft void \*(lp*
 +.Ft void \*(lp* Ns Xo
  .Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
 +.Xc
  .Pp
  or in
  .Fx Ns 's

From: Giorgos Keramidas <keramida@ceid.upatras.gr>
To: Joseph Koshy <joseph.koshy@gmail.com>
Cc: bug-followup@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Wed, 6 Oct 2004 17:59:11 +0300

 On 2004-10-06 14:18, Joseph Koshy <joseph.koshy@gmail.com> wrote:
 > Well the visual ugliness in the current manual page arises from the
 > fact that the .Ft macro forces a line break after its idea of the
 > "type" of the function.
 >
 > Using .Xo/.Xc suppresses this, and puts the whole declaration on
 > one line.
 >
 > I don't know how to suppress the inter-argument spaces inserted by
 > ".Ft".  There is probably still scope for improvement of the patch
 > below.
 
 Hah!  I think we have a winner.
 It looks ok here :-)
 
Responsible-Changed-From-To: freebsd-doc->ru 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Thu Dec 23 00:39:07 GMT 2004 
Responsible-Changed-Why:  
Ruslan, what do you think of the last diff submitted by Joseph Koshy in the 
audit trail of this PR? 

http://www.freebsd.org/cgi/query-pr.cgi?pr=72375 

From: Joseph Koshy <joseph.koshy@gmail.com>
To: Giorgos Keramidas <keramida@freebsd.org>
Cc: freebsd-doc@freebsd.org, ru@freebsd.org,
	freebsd-gnats-submit@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Thu, 23 Dec 2004 01:36:50 +0000

 Ruslan had a better fix (attached).
 
 (nemesis) $ cvs diff -u signal.3                                      
                             /usr/src.cvs/lib/libc/gen
 Index: signal.3
 ===================================================================
 RCS file: /cvs/FreeBSD/src/lib/libc/gen/signal.3,v
 retrieving revision 1.38
 diff -u -u -r1.38 signal.3
 --- signal.3    3 Jul 2004 22:30:08 -0000       1.38
 +++ signal.3    23 Dec 2004 07:13:28 -0000
 @@ -42,16 +42,24 @@
  .Lb libc
  .Sh SYNOPSIS
  .In signal.h
 -.\" The following is Quite Ugly, but syntactically correct.
 -.\" Don't try to
 -.\" fix it.
 -.Ft void \*(lp*
 -.Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
 +.\" XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
 +.\" The prototype for signal(3) cannot be cleanly marked up in -mdoc
 +.\" without the following lower-level tweak.
 +.nr in-synopsis-section 0
 +.Pp
 +.Ft "void \*(lp*" Ns
 +.Fo signal
 +.Fa "int sig"
 +.Fa "void \*(lp*func\*(rp\*(lpint\*(rp"
 +.Fc Ns
 +.Ft "\*(rp\*(lpint\*(rp" ;
  .Pp
 +.nr in-synopsis-section 1
 +.\" XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
  or in
 -.Fx Ns 's
 +.Fx Ap s
  equivalent but easier to read typedef'd version:
 -.Ft typedef "void \*(lp*sig_t\*(rp \*(lpint\*(rp" ;
 +.Vt typedef "void \*(lp*sig_t\*(rp \*(lpint\*(rp" ;
  .Ft sig_t
  .Fn signal "int sig" "sig_t func"
  .Sh DESCRIPTION

From: Giorgos Keramidas <keramida@freebsd.org>
To: Joseph Koshy <joseph.koshy@gmail.com>
Cc: freebsd-doc@freebsd.org, ru@freebsd.org,
	freebsd-gnats-submit@freebsd.org
Subject: Re: docs/72375: prototype error in signal(3)
Date: Thu, 23 Dec 2004 03:46:33 +0200

 On 2004-12-23 01:36, Joseph Koshy <joseph.koshy@gmail.com> wrote:
 > Ruslan had a better fix (attached).
 [snip relatively long diff]
 
 Great!  Are you or Ruslan going to commit this? :-)
 
State-Changed-From-To: open->closed 
State-Changed-By: jkoshy 
State-Changed-When: Thu Dec 23 02:49:38 GMT 2004 
State-Changed-Why:  
Fixed in rev 1.39 of "src/lib/libc/gen/signal.3". 

http://www.freebsd.org/cgi/query-pr.cgi?pr=72375 
>Unformatted:
