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 o58BuuFI003231 for ; Tue, 8 Jun 2010 07:56:57 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 2889014E0A1 for ; Tue, 8 Jun 2010 13:56:51 +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 9VPmUgrccrCu for ; Tue, 8 Jun 2010 13:56:49 +0200 (CEST) X-KTH-Auth: kristaps [130.237.221.96] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: discuss@mdocml.bsd.lv Received: from [130.237.221.96] (ctime.pdc.kth.se [130.237.221.96]) by smtp-2.sys.kth.se (Postfix) with ESMTP id E764E14C146 for ; Tue, 8 Jun 2010 13:56:48 +0200 (CEST) Message-ID: <4C0E323F.2090609@bsd.lv> Date: Tue, 08 Jun 2010 14:06:23 +0200 From: Kristaps Dzonsons User-Agent: Mozilla-Thunderbird 2.0.0.22 (X11/20090707) X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: "discuss@mdocml.bsd.lv" Subject: Re: OT: Vt vs. Ft/Fn (WAS: 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> <4C0D83E1.5040500@bsd.lv> <20100608000646.GE8550@iris.usta.de> <4C0E09BC.9040900@bsd.lv> <20100608100240.GV16352@danbala.tuwien.ac.at> In-Reply-To: <20100608100240.GV16352@danbala.tuwien.ac.at> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit >> mdoc.samples documents `Vt' as doing funny business in SYNOPSIS, not >> `Va' (wtf?). From what I understand, Vt's the conventional way of >> putting variables in the SYNOPSIS. `F' macros are certainly not the >> way. >> >> jmc, wiz, any suggestions and/or observations? I like Ingo's >> notation of `Vt/Va'. I've never seen it before (mdocml's manuals >> use `Vt' standalone as suggested in mdoc.samples), but you know >> better. > > I found some examples in libelf manpages (from FreeBSD) and a few in > random places. More .Vt usage like groff's mdoc(7) describes. 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. >> I think we can take this opportunity, in mdoc.7, to specify how >> variables should get documented in the SYNOPSIS. And what about the >> following: >> >> - CPP defines? >> - structs Vt's? (the `Bd' was used in one of your examples) >> >> We have `Dv' for defines, but that doesn't help me with wanting to >> print out `.Dv #define FOOBAR'. > > rpcgen(1) actually uses Dv in that case, but it's the only occurrence. > For the name of the struct, using Vt is fine, but for the struct > definition including members, there currently is no better tag than > Bd, which at least keeps it readable. Do we want to extend mdoc? I think extending mdoc for this is step down a maze of twisty passages. The SYNOPSIS should be short and sweet, I think, with a `Vt' for structs that could be fully defined later in the manual. I guess? Still no idea about defines. I see a few uses with `Fd', which makes more sense than `Dv'. Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv