From owner-freebsd-hackers@freebsd.org Fri Jan 24 23:03:05 2020 Return-Path: Delivered-To: freebsd-hackers@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 948901FF0D2 for ; Fri, 24 Jan 2020 23:03:05 +0000 (UTC) (envelope-from yp@xvoid.org) Received: from wnew2-smtp.messagingengine.com (wnew2-smtp.messagingengine.com [64.147.123.27]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 484F6c3Kysz3C2h for ; Fri, 24 Jan 2020 23:03:04 +0000 (UTC) (envelope-from yp@xvoid.org) Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailnew.west.internal (Postfix) with ESMTP id ED8F64E6 for ; Fri, 24 Jan 2020 18:03:02 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute2.internal (MEProxy); Fri, 24 Jan 2020 18:03:03 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=xvoid.org; h= subject:references:to:from:message-id:date:mime-version :in-reply-to:content-type:content-transfer-encoding; s=fm1; bh=X jbQgv8szJsTXvgYpaaxl+jYgxyqLOdgyx/RlC4jIK0=; b=uEty432JC2wW7v4o3 8TgrCQj0+NOlQ2kL3g8bYxp2IZ7hRkpl2XsUSwY5JA/xJkQznA6ULh7h5kyqrkc0 tJqmCuotUIcj9on1xomTHwaiyhQgVX0v/0Oxbns5j1FujYgoMOx9jrv3MPUGylk7 Uj+poQLa1P9snnp94Mk4Gcd6x2LxNzXLXEIAhvmL8B+Ke/Huvzn1iEQrnjBnlnPu x0i4Dyqzvr0FN8Gkgf0mHLiQRBPkZW5SROhYQBP0S8GGDL3X4QMwb3IN4EGV7y3b dcjul+w/z4trVspJp4jNf9HMmhaUEHyvmFnStA+5Xde1sGueMxZSJ2S0RFXX18Ke jKvcw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm1; bh=XjbQgv8szJsTXvgYpaaxl+jYgxyqLOdgyx/RlC4jI K0=; b=sVncuzEErffZSMP2YS9fS3hyillYEksIOID5/dIS8rItGPNOulQTUcCg6 HMauc0mn+OPS5MIn3/CVPO1Y3R4SesOjWisyrwgaITpfgvKc2rqX8C5UoUkp4qTa YTZh/k/YoKODo1vATqTpe9166XJcc8mS5XiL9jDYHk/gJmr3oHvtkrlCGj43c/Jv 0rnrQUYryzT6M5zGPUB47d1yJJ7TU9E2UgGOb4XjQpUWsSqiGl9WP09+WgUO40h6 ne5vkJlmzd9nElqoeT6rK0v8lfcUUKzxKS/mpQMCZJsuSWdPT3MmOdh/SUPUDb04 Kj7qZt6a5Rwq7HZYG0osN+t2rHTBA== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedugedrvdeigddthecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecunecujfgurhepufhfvffhkffffgggjggtgfesthejre dttdefheenucfhrhhomhepjghurhhiucfrrghnkhhovhcuoeihphesgihvohhiugdrohhr gheqnecuffhomhgrihhnpegsshgurdhlvhenucfkphepudejkedrudehhedrgedrkeelne cuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhephihpseig vhhoihgurdhorhhg X-ME-Proxy: Received: from [192.168.1.6] (unknown [178.155.4.89]) by mail.messagingengine.com (Postfix) with ESMTPA id ACB323062F4B for ; Fri, 24 Jan 2020 18:03:01 -0500 (EST) Subject: Fwd: Re: Long (-- style) options (.Fl) with mdoc(7) References: <20200124194444.GK35815@athene.usta.de> To: freebsd-hackers@freebsd.org From: Yuri Pankov X-Forwarded-Message-Id: <20200124194444.GK35815@athene.usta.de> Message-ID: Date: Sat, 25 Jan 2020 02:02:59 +0300 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:68.0) Gecko/20100101 Thunderbird/68.4.1 MIME-Version: 1.0 In-Reply-To: <20200124194444.GK35815@athene.usta.de> Content-Type: text/plain; charset=windows-1252; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 484F6c3Kysz3C2h X-Spamd-Bar: / Authentication-Results: mx1.freebsd.org; dkim=pass header.d=xvoid.org header.s=fm1 header.b=uEty432J; dkim=pass header.d=messagingengine.com header.s=fm1 header.b=sVncuzEE; dmarc=none; spf=pass (mx1.freebsd.org: domain of yp@xvoid.org designates 64.147.123.27 as permitted sender) smtp.mailfrom=yp@xvoid.org X-Spamd-Result: default: False [0.90 / 15.00]; RCVD_VIA_SMTP_AUTH(0.00)[]; R_SPF_ALLOW(0.00)[+ip4:64.147.123.27]; TO_DN_NONE(0.00)[]; RCVD_COUNT_THREE(0.00)[4]; DKIM_TRACE(0.00)[xvoid.org:+,messagingengine.com:+]; RECEIVED_SPAMHAUS_PBL(0.00)[89.4.155.178.khpj7ygk5idzvmvt5x4ziurxhy.zen.dq.spamhaus.net : 127.0.0.11]; RCVD_IN_DNSWL_LOW(-0.10)[27.123.147.64.list.dnswl.org : 127.0.5.1]; RCVD_TLS_LAST(0.00)[]; FROM_EQ_ENVFROM(0.00)[]; ASN(0.00)[asn:11403, ipnet:64.147.123.0/24, country:US]; MID_RHS_MATCH_FROM(0.00)[]; SH_EMAIL_ZRD(0.00)[0.0.0.0]; ARC_NA(0.00)[]; RECEIVED_SPAMHAUS_XBL(5.00)[89.4.155.178.khpj7ygk5idzvmvt5x4ziurxhy.zen.dq.spamhaus.net : 127.0.0.4]; R_DKIM_ALLOW(0.00)[xvoid.org:s=fm1,messagingengine.com:s=fm1]; NEURAL_HAM_MEDIUM(-0.22)[-0.216,0]; FROM_HAS_DN(0.00)[]; SH_EMAIL_DBL_DONT_QUERY_IPS(0.00)[0.0.0.0]; TO_MATCH_ENVRCPT_ALL(0.00)[]; NEURAL_HAM_LONG(-0.31)[-0.311,0]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[freebsd-hackers@freebsd.org]; DMARC_NA(0.00)[xvoid.org]; RCPT_COUNT_ONE(0.00)[1]; BAD_REP_POLICIES(0.10)[]; MIME_TRACE(0.00)[0:+]; IP_SCORE(-3.47)[ip: (-9.70), ipnet: 64.147.123.0/24(-4.92), asn: 11403(-2.68), country: US(-0.05)] X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 24 Jan 2020 23:03:05 -0000 Forwarding on behalf of Ingo as he isn't subscribed, and the message provides useful content. -------- Forwarded Message -------- Subject: Re: Long (-- style) options (.Fl) with mdoc(7) Date: Fri, 24 Jan 2020 20:44:44 +0100 From: Ingo Schwarze To: Yuri Pankov CC: freebsd-hackers@freebsd.org Hi Yuri, Yuri Pankov wrote on Fri, Jan 24, 2020 at 09:56:03PM +0300: > Steffen Nurpmeso wrote: >> Yuri Pankov wrote in : >>> Steffen Nurpmeso wrote: >>>> The very moment i have seen a showmount(8) change fly by, and >>>> wanted to make you aware of the persuading approach that NetBSD's >>>> wizd(8) uses, namely ".Fl Fl long-option". The reason why that is a bad idea is that it is semantically wrong. The meaning of ".Fl Fl long-option" is: The option "-" (as in the traditional "su -") followed by the other, additional option "-long-option" >>>> Different to ".Fl -long-option" this produces visually appealing >>>> results on all output devices. That is doubtful: $ echo .Fl Fl long-option | mandoc -mdoc -Thtml [...] --long-option [...] You get two separate elements which can screw CSS markup. >>> mandoc style guide advises differently: >>> https://mandoc.bsd.lv/mdoc/style/options.html >>> It's not authoritative, of course, but I'm not aware of any other mdoc >>> style guide. May be you could take it up to style guide/mandoc authors? >> I can Cc: him. That is _he_, who is totally opposed against long- >> options, isn't he? Yes. I consider long options a scourge - hard to document, laborious to type, and encouraging poor CLI design because they encourage excessive numbers of command line options, so program authors tend to stop considering whether yet another option is really needed. Usually, less is more. Besides, i'm not alone with that opinion: POSIX also discourages them. However, the many downsides of long options have no bearing on the fact that where they exist and do not have short aliases, they need to be documented. >> Whatever this guide says, if you do Postscript/PDF output (with >> groff) then Fl becomes a nice dash, whereas the other thing is >> a hyphen-minus. That just isn't true: $ cat tmp.mdoc .Fl \-long\-option $ groff -mdoc -Tps tmp.mdoc [...] /F0 10/Courier-Bold@0 SF(\255\255long\255option)73.666 12 Q 0 Cg EP All three dashes become the same character in -T ps output, and that is not a coincidence because the groff_mdoc(7) macros implement the .Fl macro in terms of \-: $ less /co/groff/tmac/doc.tmac-u [...] .de Fl [...] . nop \|\-\f[]\s[0]\c [...] So, *typographically*, .Fl Fl long\-option and .Fl \-long\-option produce exactly the same when disregarding \| spaces. The difference is purely *semantic*, and in that respect, .Fl Fl is clearly wrong. > Note that I don't disagree on using Fl Fl, and quite some of our man > pages already do it, I just want it documented at least somewhere so > it's possible to link to it if there's a question how something should > be done. The "Fl Fl" idiom is not so bad that it is urgent to fix it, i think there are some "Fl Fl" in OpenBSD too, but it is better avoided. Yours, Ingo