From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-2.sys.kth.se (smtp-2.sys.kth.se [130.237.32.160]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id o57NgieS031247 for ; Mon, 7 Jun 2010 19:42:45 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 2C07814C146 for ; Tue, 8 Jun 2010 01:42:38 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-2.sys.kth.se ([127.0.0.1]) by localhost (smtp-2.sys.kth.se [127.0.0.1]) (amavisd-new, port 10024) with LMTP id SuKTSRgQIWeW for ; Tue, 8 Jun 2010 01:42:27 +0200 (CEST) X-KTH-Auth: kristaps [85.8.61.243] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: discuss@mdocml.bsd.lv Received: from lappy.bsd.lv (h85-8-61-243.dynamic.se.alltele.net [85.8.61.243]) by smtp-2.sys.kth.se (Postfix) with ESMTP id E515314C022 for ; Tue, 8 Jun 2010 01:42:26 +0200 (CEST) Message-ID: <4C0D83E1.5040500@bsd.lv> Date: Tue, 08 Jun 2010 01:42:25 +0200 From: Kristaps Dzonsons User-Agent: Thunderbird 2.0.0.16 (X11/20080812) X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: "discuss@mdocml.bsd.lv" Subject: Re: Giving up on emulating SYNOPSIS vspace. References: <4C0C2CC4.3040306@bsd.lv> <20100606234253.GA24356@bramka.kerhand.co.uk> <4C0CD40F.70402@bsd.lv> <20100607232645.GD8550@iris.usta.de> In-Reply-To: <20100607232645.GD8550@iris.usta.de> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit > 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. I agree. I'm yet to find a good way to document structs. This is as good as any. And I agree: if `Ft' (and/or all SYNOPSIS-set macros) assert prior vspace for /all/ non-like elements, we'll capture this usage fine. > 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. Agreed. Pp should be a little smarter in general about when it's a noop (i.e., on a newline as it is). > 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... ;-) `Vt' is documented for use in this case. > > 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. I agree, although it should be Vt (there aren't any "F" in the Ft/Fa). > That's all i found in libc. Nice! > 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. Can you commit fixes to BSD.lv as well? Thanks, Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv