From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp1.rz.uni-karlsruhe.de (Debian-exim@smtp1.rz.uni-karlsruhe.de [129.13.185.217]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o57NQllx032584 for ; Mon, 7 Jun 2010 19:26:49 -0400 (EDT) Received: from hekate.usta.de (asta-nat.asta.uni-karlsruhe.de [172.22.63.82]) by smtp1.rz.uni-karlsruhe.de with esmtp (Exim 4.63 #1) id 1OLliP-0002uu-L1; Tue, 08 Jun 2010 01:26:45 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.71) (envelope-from ) id 1OLliP-0006RH-K2 for discuss@mdocml.bsd.lv; Tue, 08 Jun 2010 01:26:45 +0200 Received: from iris.usta.de ([172.24.96.5] helo=usta.de) by donnerwolke.usta.de with esmtp (Exim 4.69) (envelope-from ) id 1OLliP-00018p-J4 for discuss@mdocml.bsd.lv; Tue, 08 Jun 2010 01:26:45 +0200 Received: from schwarze by usta.de with local (Exim 4.71) (envelope-from ) id 1OLliP-0000gj-CJ for discuss@mdocml.bsd.lv; Tue, 08 Jun 2010 01:26:45 +0200 Date: Tue, 8 Jun 2010 01:26:45 +0200 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Subject: Re: Giving up on emulating SYNOPSIS vspace. Message-ID: <20100607232645.GD8550@iris.usta.de> References: <4C0C2CC4.3040306@bsd.lv> <20100606234253.GA24356@bramka.kerhand.co.uk> <4C0CD40F.70402@bsd.lv> X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4C0CD40F.70402@bsd.lv> User-Agent: Mutt/1.5.20 (2009-06-14) Kristaps Dzonsons wrote on Mon, Jun 07, 2010 at 01:12:15PM +0200: > It's much nicer now. Right. The code has definitely become more systematic, and i do not see any serious fallout. There a a two minor issues. 1) SYNOPSIS macros following non-SYNOPSIS-specific text ------------------------------------------------------- Consider /usr/src/lib/libc/compat-43/sigvec.3: .Sh SYNOPSIS .Fd #include .Pp .Bd -literal struct sigvec { void (*sv_handler)(); int sv_mask; int sv_flags; }; .Ed .Ft int .Fn sigvec "int sig" "struct sigvec *vec" "struct sigvec *ovec" I think this is sane usage. There is no more blank line between the .Ed and .Ft (missing term_vspace). I guess this can be easily fixed by making .Ft and friends issue a term_vspace after *any* preceding content, even regular text or random macros. Not because that would be closer to groff (not sure whether it would), but because it looks better. Besides, the .Pp after the .Fd causes *two* blank lines. One would be sufficient. But that is not important, lets just add it to the TODO list and not worry about it right now. 2) global variables ------------------- Consider /usr/src/lib/libc/rpc/svc.3: .Ft int .Fn svc_destroy "SVCXPRT *xprt" .Ft struct pollfd * .Fa svc_pollfd ; .Ft int .Fa svc_max_pollfd ; .Ft fd_set .Fa svc_fdset ; .Ft fd_set .Fa *__svc_fdset ; .Ft int .Fa __svc_fdsetsize ; .Ft int .Fa svc_fds ; .Ft int .Fn svc_freeargs "SVCXPRT *xprt" "xdrproc_t inproc" "char *in" I think this is acceptable usage; probably using .Va instead of .Fa would be a bit better, but apart from that, i wouldn't know how to express this in a better way. (NB, it wasn't RPC variable naming conventions i was trying to praise here... ;-) There is no more blank line between the .Ft/.Fa (or .Ft/.Va) pairs. It think it might be good to treat .Ft/.Fa and .Ft/.Va exactly like .Ft/.Fn. Why not just *always* issue the blank line before .Ft, whatever may be following? Wouldn't that make the code even simpler, all the while improving the results? I really can't think of any sane construct that might not want a blank line before .Ft in the synopsis - and even less find one in real manuals. That's all i found in libc. Of course, large portions of man9 are still garbled for the lack of .nr support, but that's another matter. So, i'm going to commit this to OpenBSD, we can fix the two minor issues presented above in tree, either now or later. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv