svn commit: r361940 - head/usr.bin/mkimg

[Steffen Nurpmeso]

Yuri Pankov wrote in
<bd5e499e-36a7-51cc-4130-c29a344b580d at yuripv.dev>:
 |Steffen Nurpmeso wrote:
 |> Mateusz Piotrowski wrote in
 |> <202006082111.058LBYfj075205 at repo.freebsd.org>:
 |>|Author: 0mp (doc,ports committer)
 |>|Date: Mon Jun  8 21:11:34 2020
 |>|New Revision: 361940
 |>|URL: https://svnweb.freebsd.org/changeset/base/361940
 |>|
 |>|Log:
 |>|  Use Fl instead of Ar for long flags
 |>   ...
 |>|-.Ar --formats | --schemes | --version
 |>|+.Fl -formats | Fl -schemes | Fl -version
 |> 
 |> Ingo Schwarze of mandoc has in the meanwhile committed support for
 |> ".Fl Fl", which is the term that seems to be most widely used for
 |> long options, for example
 |> 
 |>    .Fl Fl formats
 |> 
 |> It also works just fine for groff, the real roff macros that is.
 |
 |This requires quoting the actual commit message:
 |
 |     While we do not recommend the idiom ".Fl Fl long" for long options
 |     because it is an abuse of semantic macros for device-specific
 |     presentational effects, this idiom is so widespread that it makes
 |     sense to convert it to the recommended ".Fl \-long" during the
 |     validation phase.  For example, this improves HTML formatting
 |     in pages where authors have used the dubious .Fl Fl.
 |
 |So, FWIW, while the support for ".Fl Fl" was added, using it is not 
 |recommended.

I do not follow, sorry.

I for one think Fl Fl is absolutely valid, where is the problem?
If you go that route that Ingo (it is Ingo) brings into the world
here (which counteracts many, many real-life manuals), then just
reach into the macros and check how many characters the argument
to Fl has, after all Fl is meant to document getopt-style things.
If it is one, it is a short option, if it has more, it is a long
one.  Short options have one dash, long have two, that is the
convention.

That is, mdoc(7) is BSDs own, the macros have always been there,
until groff has been replaced with mandoc, at least, but instead
of just adding an easy .if (.ie, actually) roff condition check on
a .length there is, dict.cc says: topsy-turvy.

So whining on lost semantics is misplaced anyhow.  With Fl Fl you
can programmatically check easily (what you have to do with mdoc
anyway because it is not "^.Fl .Fl bla" or "^.It .Fl .Fl bla", no,
it is "^.It Fl bla", heh), whereas with Fl \-bla you have to parse
actual string content to get semantic, at least in my opinion.  It
is a long option, not a short option, that requires special
treatment, and is not even standardized until now.
Just my one cent, of course.

--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)