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

[Steffen Nurpmeso]

Hello.

Sorry for the late reply.

Yuri Pankov wrote in <d762aedb-24f9-7576-1f16-2ce98470ac04 at xvoid.org>:
 |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"

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="Fl">-</code><code class="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 = Ns Ar value Ns Oc Ns : Ns Oc

»Klar wie Kloßbrühe«.

  ...
 |    $ 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 
 |> 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.

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)