Fl Fl for long options

Fl Fl for long options

[Anthony J. Bentley]

Hi Ingo,

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

Interpreting "Fl Fl foo" as "empty flag followed by flag foo" simply
doesn't make sense to me. 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--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?

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

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Fl Fl for long options

[Ingo Schwarze]

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

Re: Fl Fl for long options

[Anthony J. Bentley]

Hi Ingo,

Ingo Schwarze writes:
> > 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.
>   [...]

Hm, so it has. That's what I get for not updating this machine lately.

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

Thanks, this helps me understand your reasoning.

> 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".
> ...
> Going forward, some of this discussion has now become moot.

Fair enough.

So, Ingo, it seems that you provided the solution before I even asked
my question! Would that all problems in my life could be resolved in
such a way.

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv