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 o57B2nbE014668 for ; Mon, 7 Jun 2010 07:02:49 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by smtp-2.sys.kth.se (Postfix) with ESMTP id 7D1A114E082 for ; Mon, 7 Jun 2010 13:02:43 +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 KHrsXTh5uUKH for ; Mon, 7 Jun 2010 13:02:42 +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 6C9B214E27C for ; Mon, 7 Jun 2010 13:02:41 +0200 (CEST) Message-ID: <4C0CD40F.70402@bsd.lv> Date: Mon, 07 Jun 2010 13:12:15 +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: Giving up on emulating SYNOPSIS vspace. References: <4C0C2CC4.3040306@bsd.lv> <20100606234253.GA24356@bramka.kerhand.co.uk> In-Reply-To: <20100606234253.GA24356@bramka.kerhand.co.uk> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit > i propose you do whatever you think makes sense: a simple synopsis with > workable rules is preferable to a bug-compatible groff. Done and committed. Ingo, please let me know if you experience fall-out and we can tweak as necessary. If it's ok, I'll tag the version and we can move on. >From mdoc.7 (note, by the way, mandoc(1) has a new output option -Owidth=xxx that allows me to paste this into this mail so nicely): SYNOPSIS Documents the utility invocation syntax, function call syntax, or device configuration. For the first, utilities (sections 1, 6, and 8), this is generally structured as follows: .Nm foo .Op Fl v .Op Fl o Ar file .Op Ar .Nm bar .Op Fl v .Op Fl o Ar file .Op Ar For the second, function calls (sections 2, 3, 9): .Vt extern const char *global; .In header.h .Ft "char *" .Fn foo "const char *src" .Ft "char *" .Fn bar "const char *src" And for the third, configurations (section 4): .Cd "it* at isa? port 0x2e" .Cd "it* at isa? port 0x4e" Manuals not in these sections generally don't need a SYNOPSIS. Some macros are displayed differently in the SYNOPSIS section, particularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft. All of these macros are output on their own line. If two such dissimilar macros are pair-wise invoked (except for Ft before Fo or Fn), they are separated by a vertical space, unless in the case of Fo, Fn, and Ft, which are always separated by vertical space. > i know you don;t want to talk about the simpler cases but i have to add: > can we make synopsis nice please? Bk/Ek is broken, and we need a nice > synopsis. are we far away? let's take this from openbsd's isakmpd.8: > > isakmpd [-46adKLnSTv] [-c config-file] [-D class=level] [-f fifo] [-i > pid-file] [-l packetlog-file] [-N udpencap-port] [-p listen-port] [-R > report-file] > > i'd like this, by default: > > isakmpd [-46adKLnSTv] [-c config-file] [-D class=level] [-f fifo] > [-i pid-file] [-l packetlog-file] [-N udpencap-port] > [-p listen-port] [-R report-file] > > ignore any crappy Bk/Ek stuff. just format nicely please. it's a real > killer for mandoc right now, i feel. by the way, it's how groff > currently formats it. i've no idea if it's coincidence or sth else. One of the reasons of fixing vertical spacing was to pave the way for this. Before doing so, there was too much chaos between -T[x]html and -Tascii in the various macro handlers. It's much nicer now. Thanks, Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv