Bug 72375

Comment 1 Giorgos Keramidas 2004-10-06 09:53:41 UTC

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 ;-)

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

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.

> 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

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 :-)

Comment 6 Giorgos Keramidas 2004-12-23 00:39:07 UTC

Responsible Changed
From-To: freebsd-doc->ru

Ruslan, what do you think of the last diff submitted by Joseph Koshy in the 
audit trail of this PR?

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

Comment 8 Giorgos Keramidas 2004-12-23 01:46:33 UTC

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? :-)

Comment 9 Joseph Koshy 2004-12-23 02:49:38 UTC

State Changed
From-To: open->closed

Fixed in rev 1.39 of "src/lib/libc/gen/signal.3".