Re: .Li hiccup (and \*(Pu issue)

[Ingo Schwarze <schwarze@usta.de>]

Hi Kristaps,

Kristaps Dzonsons wrote on Tue, May 25, 2010 at 10:42:33PM +0200:
> Jason wrote:
>> Kristaps wrote:
>>> Jason wrote:

>>>> found a blip whereby Li seems to be doing something weird.
>>>> from expr.1:
>>>>
>>>>	.It Ar expr1 Li : Ar expr2
>>>>
>>>>	groff:	expr1 : expr2
>>>>	mandoc: expr1: expr2
>>>>
>>>> to be honest, Li is treating the colon as punctuation, and i'd kind of
>>>> expect that. but groff does not. so i'm not sure what way you want to
>>>> go.

>>> Seems this can be generalised: in-line macros treat closing punctuation
>>> differently when it's used as the first term; namely, the treat it like
>>> a normal word.  So
>>>
>>>  .Fl . a b
>>>
>>> becomes
>>>
>>> -. -a -b

I guess you misunderstand what is happening here.
The result is not Fl(.) Fl(a) but Fl() text(.) Fl(a).
Compare to

  .Ar : a

which gives

  file ...: a

where the dots are underlined, but the colon is not, so the colon is
outside the macro scope - of course, you can see that with .Ar, but
you can't see that with .Fl or .Li.

So, in a line macro, leading *opening* (and middle) punctuation will
delay macro opening, but leading *closing* punctuation will not.
That is, the logic must be:

  macro scope closed
  start argument loop
    if !open && (text || (closing punctuation && never open))
      open macro scope
    if open && punctuation:
      close macro scope
    put text element
  end argument loop
  if open:
    close macro scope

Look at this:

  .Ar [ ( : ( :

It gives:

  [(file ...: (:

That is text([) text(() Ar() text(:) text(() (*) text(:);
note that Ar() is not again opened at (*) - so, closing
punctuation opens the macro only once, whereas text opens
it every time.

>>> I've come to have a rule of thumb:  if we can't explain something
>>> in a single mdoc.7 sentence, we shouldn't be following it.

I don't think we need to explain much about this, it is easy.
Perhaps just:

   In-line
     Opening of these macros is delayed by one or more leading "["
     and "(" characters.  These macros are interrupted by Reserved
     Characters, but reopen afterwards in case additional arguments
     follow.  They are closed by subsequent macros, after the maximum
     number of arguments is reached, or at the end of the line.

>> well, i'm not sure. i can see reasons for and against. nothing is
>> documented in mdoc.samples.7 really. it just says that macros can handle
>> punctuation. but given that this would be an exception,

I don't see an exception.
Isn't it playing by the rules?

>> and that the behaviour does not conform with groff, i'd be tempted
>> to say we'd be better off emulating it.

Unless i'm missing something, i tend to agree.

> I respectively suggest, in this case, that the invocations be fixed.
> I think that people have confused `Li' as meaning "what follows is
> interpreted in literal mode", instead of "is rendered in a fixed
> font", as this behaviour is only used for `Li' and not for any other
> macro, to wit (on OpenBSD):
> 
> % egrep 'Li [:.;] ' `cat manuals.txt `
> usr.sbin/bgpd/bgpd.conf.5:.Ar as-number Ns Li : Ns Ar local ,

Cargo-cult alert:  Why not just

  .Ar as-number : Ns Ar local ,

That seems to work with all our formatters, and i don't see why
it shouldn't work, or why we should put any more macros in there.

> usr.sbin/bgpd/bgpd.conf.5:.Ar subtype Ar as-number Ns Li : Ns Ar local
> usr.sbin/bgpd/bgpd.conf.5:.Ar subtype Ar IP Ns Li : Ns Ar local
> usr.sbin/bgpd/bgpd.conf.5:.Ar as-number Ns Li : Ns Ar local
> usr.sbin/bgpd/bgpd.conf.5:.Ar as-number Ns Li : Ns Ar local ,
> usr.sbin/bgpd/bgpd.conf.5:.Ar subtype Ar as-number Ns Li : Ns Ar local
> usr.sbin/bgpd/bgpd.conf.5:.Ar subtype Ar IP Ns Li : Ns Ar local
> usr.sbin/bgpd/bgpd.conf.5:.Ar as-number Ns Li : Ns Ar local .
> usr.sbin/bgpd/bgpd.conf.5:.Ar IP Ns Li : Ns Ar local .
> bin/expr/expr.1:.It Ar expr1 Li : Ar expr2

This ought to parse as Ar(expr1) Li() text(:) Ar(expr2).
But currently we parse it as Ar(expr1) text(:) Ar(expr2).

I guess we shouldn't drop the empty .Li.
A macro following a macro will assert a space,
then the Li will find itself empty and not print anything,
then punctuation following a macro will use TERMP_NOSPACE
and not assert a second space before printing the colon.
I admit, not tested, but that is how it should work.

That said, i think

  .Ar expr1 No : Ar expr2

is easier to understand and might look better in variable-width
output - of course, it is currently broken in the same way as
in the .Li, .Fl and .Ar cases, the empty .No is missing from
the syntax tree just like the other ones.

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