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 o5CI5DMn007604 for ; Sat, 12 Jun 2010 14:05:14 -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 1ONV4y-0005Hg-7L; Sat, 12 Jun 2010 20:05:12 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.71) (envelope-from ) id 1ONV4y-00044z-5a for discuss@mdocml.bsd.lv; Sat, 12 Jun 2010 20:05:12 +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 1ONV4y-0000v8-4X for discuss@mdocml.bsd.lv; Sat, 12 Jun 2010 20:05:12 +0200 Received: from schwarze by usta.de with local (Exim 4.71) (envelope-from ) id 1ONV4y-0005gY-3W for discuss@mdocml.bsd.lv; Sat, 12 Jun 2010 20:05:12 +0200 Date: Sat, 12 Jun 2010 20:05:12 +0200 From: Ingo Schwarze To: discuss@mdocml.bsd.lv Subject: Re: Vt vs. Ft/Fn Message-ID: <20100612180512.GF6086@iris.usta.de> References: <4C0C2CC4.3040306@bsd.lv> <20100606234253.GA24356@bramka.kerhand.co.uk> <4C0CD40F.70402@bsd.lv> <20100607232645.GD8550@iris.usta.de> <4C0D83E1.5040500@bsd.lv> <20100608000646.GE8550@iris.usta.de> <4C0E09BC.9040900@bsd.lv> <20100608100240.GV16352@danbala.tuwien.ac.at> <4C0E323F.2090609@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: <4C0E323F.2090609@bsd.lv> User-Agent: Mutt/1.5.20 (2009-06-14) Hi Kristaps, hi Thomas, Kristaps Dzonsons wrote on Tue, Jun 08, 2010 at 02:06:23PM +0200: > I think the following makes sense. Let `Vt' work as it does right now, > but let's adopt `Vt/Va' as being the conventional form for labelling > variables in the SYNOPSIS. > > Pros: consistent with Ft/Fn et al.; much richer semantic annotation; > more intuitive (subjective, of course); backwards-compatible with > plain-old `Vt'. > > How does this sound? I'm really wary about changing convention, but > this seems like an area that really needs it. Sounds reasonable, though i might be missing some aspect of how .Vt is traditionally used. Currently, groff formats .Vt/.Va with a line break, just like .Ft/.Fa. To implement your idea, that behaviour would need to be changed, both in mandoc and in current upstream groff. So we should postpone this and just stick with traditional .Vt for now. But i have taken a note in my personal long-term TODO list (not to be confused with the public short-term TODO file on bsd.lv). > Thomas Klausner wrote: >> Kristaps wrote: >>> I think we can take this opportunity, in mdoc.7, to specify how >>> variables should get documented in the SYNOPSIS. For now, i think recommending traditional .Vt is fine. >>> And what about the following: >>> >>> - CPP defines? >>> - structs Vt's? (the `Bd' was used in one of your examples) I wouldn't worry about documenting that right now, at least not before fixing mandoc to get the vertical spacing around .Bd used for structs right, and even that is not terribly high priority (as compared to .Nm/.Fn indenting and .Bk, for example). >> Do we want to extend mdoc? Certainly not right now! Before it makes sense to suggest changing the rules, we should first be able to play by them, and we should also, after that, document them thoroughly. Otherwise, we would only add to the chaos. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv