Re: [Groff] mdoc(7) interpretation differences (maybe groff bug)

[Ingo Schwarze]

Hi Werner and Steffen,

Werner LEMBERG wrote on Sat, Nov 08, 2014 at 02:19:38PM +0100:
> Steffen Nurpmeso wrote:

>> [...] i stumbled over a interpretation difference (full source
>> attached):
>> 
>> source:
>>   .It Fn at_quick_exit , Fn _atexit
>>   groff and mandoc agree.
>>   .It Fn at_quick_exit , _atexit
>>   Only mandoc gets that right.
>> 
>> mandoc:
>>      at_quick_exit(), _atexit()
>>                      groff and mandoc agree.
>> 
>>      at_quick_exit(), _atexit()
>>                      Only mandoc gets that right.
>> 
>> groff (1.22.3)
>>      at_quick_exit(), _atexit()
>>                 groff and mandoc agree.
>> 
>>      at_quick_exit(), _atexit
>>                 Only mandoc (and mdocmx) gets that right.
>> 
>> From my understanding of the manual

> Where have you read this?

I suspect Steffen is talking about this paragraph in the mdoc(7)
manual from the mandoc distribution:

MACRO SYNTAX
   [...]
   Delimiters
     When a macro argument consists of one single input character considered
     as a delimiter, the argument gets special handling.  This does not apply
     when delimiters appear in arguments containing more than one character.
     [...]
     Many in-line macros interrupt their scope when they encounter delimiters,
     and resume their scope when more arguments follow that are not
     delimiters.  For example,
           .Fl a ( b | c \*(Ba d ) e
     renders as:
           -a (-b | -c | -d) -e

Note that the text is somewhat fuzzy.  It talks about *many* in-line
macros and doesn't say which ones this applies to.  The reason for
the fuzziness is that i never found the time time to investigate
all the cases, even though i investigated many of them.

I certainly wouldn't recommend putting multiple function names on
one macro input line; i'm not really surprised that handling turns
out to be implementation dependent.  The syntax of the .Fn macro
is already fairly complicated:  one mandatory argument, then zero
or more optional arguments with semantics differering from the
semantics of the first argument.

Indeed, mandoc does treat .Fn as an in-line macro (in particular
outside the SYNOPSIS).  But i never thought about what should
happen when .Fn is interrupted by punctuation.  The mandoc
behaviour of reopening a new scope afterwards is not intentional,
it's just what the code (shared with .Fl and many other macros)
happens to be doing right now.

I have taken a note in the mandoc TODO file.  When i come round
to investigate more closely, chances are i will make mandoc
conform to what groff does in this case.

>> the latter is a valid form to mark "_atexit" as a .Fn, in which case
>> the mdoc macros have a bug?

> I would rather say the opposite: the comma ends the list of function
> parameters of `Fn'.

Not 100% sure yet, but my first impression is that might indeed
be the saner choice.

Yours,
  Ingo