Re: Fl Fl for long options

[Ingo Schwarze <schwarze@usta.de>]

Hi Anthony,

Anthony J. Bentley wrote on Sun, Apr 26, 2020 at 04:59:03PM -0600:
> schwarze@mandoc.bsd.lv writes:

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

> Since we've had this discussion before, I feel like I must reiterate my
> disagreement here. "Fl Fl" is a perfectly natural way to represent long
> options and it's how I've always done it.
> 
> And again, I still find it incredibly unintuitive that in OpenBSD's
> grep(1) manual jumping to the --label tag unintuitively requires
> searching for "-label" rather than "label".

That had already been fixed for some time before this commit:

   $ man -O tag=label grep
     --label=name
             Print name instead of the filename before lines.
  [...]

The code is in tag.c, function tag_put().  If a word is being
automatically tagged and that word starts with "-", "\-", "\&", or
"\e", then that prefix is automatically skipped and the rest of the
word becomes the tag.  This also supports usage like this:

   $ man -O tag=p roff
     \p      Break the output line at the end of the current word.
  [...]

There is additional code in man_validate that even skips font escapes
in such a position; that code is not used for mdoc(7) because nobody
in their right mind uses \f in mdoc(7) documents and is somewhat
dislike running unnecessary code.  For example:

   $ man -O tag=D cvs
    -D date_spec
           Use the most recent revision no later than date_spec (a single
  [...]
   $ grep -C1 -m1 date_spec $(man -w 1 cvs)
  .TP
  \fB\-D\fP \fIdate_spec\fP


> Interpreting "Fl Fl foo" as "empty flag followed by flag foo" simply
> doesn't make sense to me.

It is not so much something that requires an active interpretation,
it already follows from the structure of the language itself.  Macros
in mdoc(7) and man(7) form a tree structure.  In many cases, whether
adjacent macros will become siblings or parent and child requires
knowledge about the language that isn't apparent from the syntax,
and in a few cases, there are equivalent possibilities for the
relative positioning of the nodes in the tree that would ultimately
result in the same formatting, but that each macro generates a node
can hardly be questioned.  It is also clear that .Fl is an in-line
macro and that in-line macros only extend to the next in-line macro
or to the end of the line.

So there can be no doubt that the syntactical meaning of "Fl Fl foo"
is "an empty flag and a flag foo".

> I'm aware there are cases like lprm(1) and
> tset(1) that have an empty flag. Even if those were typical examples--
> and they are decidedly not--

Granted.

> where in those pages would it ever make
> sense to use that empty flag adjacent to another? Is there a single
> manpage anywhere that ever uses "Fl Fl" to mean something *other* than
> long options?

I'm not aware of any, and that is why i decided to implement this
syntactical conversion to have "empty flag immediately before
non-empty flag" transformed to "flag with double hyphen-minus".

> Maybe I just don't understand how this works. But considering the
> prevalence of Fl Fl as long option, clearly I'm not alone.

I suspect this prevelence resulted from a tradition of "tweak the
input until the formatting looks how you want it in the output mode
you care about" rather than a tradition of "mark up the text in a
logical way and let the formatters decide on a reasonable formatting
in each output mode".  At least jmc@ repeatedly said that's the way
he worked before the advent of mandoc, simply because no other mode
of working yielded acceptable formatting during those times.

Going forward, some of this discussion has now become moot.
With mandoc, ".Fl Fl foo" is now the same for all output modes as
".Fl \-foo".  So it's no longer much of a question which one produces
better output, except for minor aspects:  ".Fl \-foo" is still more
robust even with mandoc because stuff that is written correctly in
the first place is always more robust than stuff that requires
transformation in the validator: for example ".Fl Fl foo" might
still cause trouble when you explicitly try to .Tg it because then
the two validation routines involved can end up fighting each other,
one undoing the benefits of the other (i paid attention though to
make sure that automatic tagging works with .Fl Fl).  Also, no
parser other than mandoc will do the transformation, so ".Fl \-foo"
is still more portable.

That's why i would still recommend ".Fl \-foo" over ".Fl Fl foo":
robustness, portability, and more logical in the first place.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv