Date: Sat, 25 Jan 2020 02:02:59 +0300 From: Yuri Pankov <yp@xvoid.org> To: freebsd-hackers@freebsd.org Subject: Fwd: Re: Long (-- style) options (.Fl) with mdoc(7) Message-ID: <d762aedb-24f9-7576-1f16-2ce98470ac04@xvoid.org> In-Reply-To: <20200124194444.GK35815@athene.usta.de> References: <20200124194444.GK35815@athene.usta.de>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <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
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
[...]
<code class="Fl">-</code><code class="Fl">-long-option</code>
[...]
You get two separate <code> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?d762aedb-24f9-7576-1f16-2ce98470ac04>