Date: Mon, 27 Jan 2020 17:27:13 +0100 From: Steffen Nurpmeso <steffen@sdaoden.eu> To: Yuri Pankov <yp@xvoid.org> Cc: freebsd-hackers@freebsd.org, Ingo Schwarze <schwarze@usta.de> Subject: Re: Fwd: Re: Long (-- style) options (.Fl) with mdoc(7) Message-ID: <20200127162713.9UoUn%steffen@sdaoden.eu> In-Reply-To: <d762aedb-24f9-7576-1f16-2ce98470ac04@xvoid.org> References: <20200124194444.GK35815@athene.usta.de> <d762aedb-24f9-7576-1f16-2ce98470ac04@xvoid.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Hello. Sorry for the late reply. Yuri Pankov wrote in <d762aedb-24f9-7576-1f16-2ce98470ac04@xvoid.org>: |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 <schwarze@usta.de> |To: Yuri Pankov <yp@xvoid.org> |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 <d07ec64e-5ad1-0960-d14b-a446077ee25b@xvoid.org>: |>>> 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 | [...] | <code class=3D"Fl">-</code><code class=3D"Fl">-long-option</code> | [...] I think it would be worth adding special code to make it happen, then. |You get two separate <code> 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)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20200127162713.9UoUn%steffen>