Wrong treatment of ".Nm ."

Wrong treatment of ".Nm ."

[Ulrich Spörlein]

Hi,

dump.8 on FreeBSD starts roughly like this:

.Dd February 24, 2006
.Dt DUMP 8
.Os
.Sh NAME
.Nm dump ,
.Nm rdump
.Nd file system backup
.Sh SYNOPSIS
.Nm
.Op Fl T Ar date
.Ar filesystem
.Nm
.Fl W | Fl w
.Pp
.Nm rdump
is an alternate name for
.Nm .
.Pp
.in \" XXX
(The
.Bx 4.3
option syntax is implemented for backward compatibility, but
is not documented here.)
.Sh DESCRIPTION
The
.Nm
utility examines files



And mandoc will misrender the .Nm . like this:

     rdump is an alternate name for
     .

when it should do this:

     rdump is an alternate name for dump.


Also, groff will indent the sentence in parenthesis unless the ".in"
suppresses that. mandoc doesn't know ".in" but behaves like it is set.
Not sure if you want to follow what groff is doing here ...

Uli
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Wrong treatment of ".Nm ."

[Ulrich Spörlein]

On Thu, 02.06.2011 at 11:03:51 +0200, Ulrich Spörlein wrote:
> Hi,
> 
> dump.8 on FreeBSD starts roughly like this:
> 
> .Dd February 24, 2006
> .Dt DUMP 8
> .Os
> .Sh NAME
> .Nm dump ,
> .Nm rdump
> .Nd file system backup
> .Sh SYNOPSIS
> .Nm
> .Op Fl T Ar date
> .Ar filesystem
> .Nm
> .Fl W | Fl w
> .Pp
> .Nm rdump
> is an alternate name for
> .Nm .
> .Pp
> .in \" XXX
> (The
> .Bx 4.3
> option syntax is implemented for backward compatibility, but
> is not documented here.)
> .Sh DESCRIPTION
> The
> .Nm
> utility examines files
> 
> 
> 
> And mandoc will misrender the .Nm . like this:
> 
>      rdump is an alternate name for
>      .
> 
> when it should do this:
> 
>      rdump is an alternate name for dump.
> 
> 
> Also, groff will indent the sentence in parenthesis unless the ".in"
> suppresses that. mandoc doesn't know ".in" but behaves like it is set.
> Not sure if you want to follow what groff is doing here ...

Found one more difference:

Usage of the
.Ns Nm
utility:

in groff will *not* add a newline while in the Synopsis section. Mandoc
will ignore .Ns and break the sentence.

Uli
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Wrong treatment of ".Nm ."

[Ingo Schwarze]

Hi Ulrich,

Ulrich Spörlein wrote on Thu, Jun 02, 2011 at 11:33:35AM +0200:

>> .Sh SYNOPSIS
[...]
>> .Pp
>> .Nm rdump
>> is an alternate name for
>> .Nm .

[...]
> Usage of the
> .Ns Nm
> utility:

You are right, these are subtle mandoc bugs, i have added a TODO entry:

 - When there is free text in the SYNOPSIS and that free text contains
   the .Nm macro, groff somehow understands to treat the .Nm as an in-line
   macro, while mandoc treats it as a block macro and breaks the line.
   No idea how the logic for distinguishing in-line and block instances
   should be, needs investigation.
   uqs@  Thu, 2 Jun 2011 11:03:51 +0200
   uqs@  Thu, 2 Jun 2011 11:33:35 +0200

Free text in the SYNOPSIS is perhaps not very good style,
but that's no reason for mandoc to behave differently.

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