From owner-freebsd-hackers@freebsd.org Mon Jan 27 16:27:23 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 542FD1FB1E9 for ; Mon, 27 Jan 2020 16:27:23 +0000 (UTC) (envelope-from steffen@sdaoden.eu) Received: from sdaoden.eu (sdaoden.eu [217.144.132.164]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 485wBd0rfPz4YB5 for ; Mon, 27 Jan 2020 16:27:20 +0000 (UTC) (envelope-from steffen@sdaoden.eu) Received: by sdaoden.eu (Postfix, from userid 1000) id 780C616054; Mon, 27 Jan 2020 17:27:13 +0100 (CET) Date: Mon, 27 Jan 2020 17:27:13 +0100 From: Steffen Nurpmeso To: Yuri Pankov Cc: freebsd-hackers@freebsd.org, Ingo Schwarze Subject: Re: Fwd: Re: Long (-- style) options (.Fl) with mdoc(7) Message-ID: <20200127162713.9UoUn%steffen@sdaoden.eu> In-Reply-To: References: <20200124194444.GK35815@athene.usta.de> Mail-Followup-To: Yuri Pankov , freebsd-hackers@freebsd.org, Ingo Schwarze User-Agent: s-nail v14.9.16-88-gce582480-dirty OpenPGP: id=EE19E1C1F2F7054F8D3954D8308964B51883A0DD; url=https://ftp.sdaoden.eu/steffen.asc; preference=signencrypt BlahBlahBlah: Any stupid boy can crush a beetle. But all the professors in the world can make no bugs. MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Queue-Id: 485wBd0rfPz4YB5 X-Spamd-Bar: / Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of steffen@sdaoden.eu designates 217.144.132.164 as permitted sender) smtp.mailfrom=steffen@sdaoden.eu X-Spamd-Result: default: False [0.25 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.86)[-0.862,0]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[3]; R_SPF_ALLOW(-0.20)[+a]; MIME_GOOD(-0.10)[text/plain]; DMARC_NA(0.00)[sdaoden.eu]; TO_DN_SOME(0.00)[]; TO_MATCH_ENVRCPT_SOME(0.00)[]; NEURAL_SPAM_LONG(0.12)[0.124,0]; MID_CONTAINS_FROM(1.00)[]; RCVD_COUNT_ZERO(0.00)[0]; FROM_EQ_ENVFROM(0.00)[]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:15987, ipnet:217.144.132.0/24, country:DE]; IP_SCORE(0.29)[asn: 15987(1.48), country: DE(-0.02)] 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: Mon, 27 Jan 2020 16:27:23 -0000 Hello. Sorry for the late reply. Yuri Pankov wrote in : |Forwarding on behalf of Ingo as he isn't subscribed, and the message=20 |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=20 |other, additional option "-long-option" I really think you are splitting hairs here. Long options are a very common thing, and using "Fl Fl opt" as opposed to "Fl -opt" seems to fit the task more nicely for me; having a special command for this would be even better, but that we do not have. The option is "opt", not "-opt". |>>>> 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 | [...] I think it would be worth adding special code to make it happen, then. |You get two separate elements which can screw CSS markup. Hm. |>>> 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, ... |with that opinion: POSIX also discourages them. ... |>> 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 ... But this is "Fl \-opt", then. I did not use that back in the day, before i saw wizd's comment "i would use Fl Fl", and it made a difference for me by then. I mean, the nice clean semantic syntax of mdoc(7) as opposed to man(7) where you work with \- anyway is appealing: .Op : Ns Fl C Ar """field:\0body""" Ns \&: .Op : Ns Fl c Ar cc-addr Ns \&: .Op Fl M Ar type | Fl m Ar file | Fl q Ar file | Fl t .Op Fl r Ar from-addr .Oo : Ns Fl S\0 Ns Ar var Ns Oo Ns =3D Ns Ar value Ns Oc Ns : Ns Oc =C2=BBKlar wie Klo=C3=9Fbr=C3=BChe=C2=AB. ... | $ 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. Hm, maybe i should use \- for inter-argument-word separators, too. "Ns Fl" would surely be false for those.. |> Note that I don't disagree on using Fl Fl, and quite some of our man=20 |> pages already do it, I just want it documented at least somewhere so=20 |> it's possible to link to it if there's a question how something should= =20 |> 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. I only did not use it because i did not know it works. --steffen | |Der Kragenbaer, The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)