Fwd: Re: Long (-- style) options (.Fl) with mdoc(7)

[Yuri Pankov]

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 at usta.de>
To: Yuri Pankov <yp at xvoid.org>
CC: freebsd-hackers at 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 at 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 at 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