Small rendering difference between nroff and mandoc

Small rendering difference between nroff and mandoc

[Nicolas Joly]

Hi,

I recently started checking for differences between nroff and mandoc
output for the NetBSD manpages. And noticed a small spacing difference
between the tools. When a sentence ends with a macro followed by a
punctuation mark mandoc does only output a single space character but
nroff adds two.

By example with the select(2) man page :

njoly@lanfeust [~]> cat /usr/share/man/man2/select.2
[...]
a larger definition of
.Dv FD_SETSIZE
before the inclusion of
.In sys/types.h .
The kernel will cope,and the userland libraries provided with the
system are also ready for large numbers of file descriptors.
[...]

njoly@lanfeust [~]> nroff -mandoc /usr/share/man/man2/select.2
[...]
     providing a larger definition of FD_SETSIZE before the inclusion of
     <sys/types.h>.  The kernel will cope,and the userland libraries provided
     with the system are also ready for large numbers of file descriptors.

njoly@lanfeust [~]> mandoc /usr/share/man/man2/select.2
[...]
     by providing a larger definition of FD_SETSIZE before the inclusion of
     <sys/types.h>. The kernel will cope,and the userland libraries provided
     with the system are also ready for large numbers of file descriptors.

Thanks in advance,
Regards.

-- 
Nicolas Joly

Biology IT Center
Institut Pasteur, Paris.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Small rendering difference between nroff and mandoc

[Ingo Schwarze]

Salut Nicolas,

Nicolas Joly wrote on Fri, Oct 12, 2012 at 05:00:36PM +0200:

> I recently started checking for differences between nroff and mandoc
> output for the NetBSD manpages.

Nice to hear that, thanks!

> And noticed a small spacing difference
> between the tools. When a sentence ends with a macro followed by a
> punctuation mark mandoc does only output a single space character but
> nroff adds two.

Neither the groff nor the mandoc side is as simple as that.

For partial implicit block macros, mandoc does end-of-sentence (EOS)
spacing already, e.g.

  .Pq enclosed .
  following

Also, groff only does that when the punctuation mark appears isolated,
not when it appears at the end of a word, e.g.

  .\" fstat(1)
  .Ux Ns -domain.
  A unidirectional

And groff doesn't do that when the isolated mark appears in the
middle of the line.

So, it only affects certain macros, and in a non-trivial way.
In OpenBSD base, i see one single instance of this issue,
in open(2).

In any case, this is rather rare and of relatively little impact,
compared to other remaining EOS issues.  Still, it ought to be
fixed eventually.  For now, i'm adding this to

  http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml

 - Trailing isolated dots lack EOS for some macros.
   This cannot use mandoc_eos() because groff only does EOS 
   for isolated dots at least in some of these cases.
   Affected macros included those using in_line_eoln().
   Make sure to fix open(2) 
   without breaking fstat(1), ksh(1), tzset(3) and UKC(8).
   reported by Nicolas Joly  Fri, 12 Oct 2012 17:00:36 +0200

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

Re: Small rendering difference between nroff and mandoc

[Nicolas Joly]

On Fri, Oct 12, 2012 at 06:46:37PM +0200, Ingo Schwarze wrote:
> Nicolas Joly wrote on Fri, Oct 12, 2012 at 05:00:36PM +0200:
> 
> > I recently started checking for differences between nroff and mandoc
> > output for the NetBSD manpages.
> 
> Nice to hear that, thanks!

Yep. I find that way a few strange/bad/... constructs that render
differently with both formatters.

> > And noticed a small spacing difference
> > between the tools. When a sentence ends with a macro followed by a
> > punctuation mark mandoc does only output a single space character but
> > nroff adds two.
> 
> Neither the groff nor the mandoc side is as simple as that.

Otherwise it would have already been fixed ;)

[...]
> In OpenBSD base, i see one single instance of this issue,
> in open(2).

Actually i do see about 150 man pages in the NetBSD base system
(e.g. in /usr/share/man) that exhibit a similar behaviour ...

> In any case, this is rather rare and of relatively little impact,
> compared to other remaining EOS issues.  Still, it ought to be
> fixed eventually.  For now, i'm adding this to
> 
>   http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?cvsroot=mdocml
> 
>  - Trailing isolated dots lack EOS for some macros.
>    This cannot use mandoc_eos() because groff only does EOS 
>    for isolated dots at least in some of these cases.
>    Affected macros included those using in_line_eoln().
>    Make sure to fix open(2) 
>    without breaking fstat(1), ksh(1), tzset(3) and UKC(8).
>    reported by Nicolas Joly  Fri, 12 Oct 2012 17:00:36 +0200

Thanks.

-- 
Nicolas Joly

Biology IT Center
Institut Pasteur, Paris.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Small rendering difference between nroff and mandoc

[Ingo Schwarze]

Salut Nicolas,

Nicolas Joly wrote on Fri, Oct 12, 2012 at 05:00:36PM +0200:

> I recently started checking for differences between nroff and mandoc
> output for the NetBSD manpages. And noticed a small spacing difference
> between the tools. When a sentence ends with a macro followed by a
> punctuation mark mandoc does only output a single space character but
> nroff adds two.

As far as i could reproduce, two particular macros were affected,
namely .In and .Ap.  I just fixed those two in both OpenBSD and bsd.lv.

Should you find more, it would be kind if you could speak up again!

Thanks again for the report,
  Ingo

> By example with the select(2) man page :
> 
> njoly@lanfeust [~]> cat /usr/share/man/man2/select.2
> [...]
> a larger definition of
> .Dv FD_SETSIZE
> before the inclusion of
> .In sys/types.h .
> The kernel will cope,and the userland libraries provided with the
> system are also ready for large numbers of file descriptors.
> [...]
> 
> njoly@lanfeust [~]> nroff -mandoc /usr/share/man/man2/select.2
> [...]
>      providing a larger definition of FD_SETSIZE before the inclusion of
>      <sys/types.h>.  The kernel will cope,and the userland libraries provided
>      with the system are also ready for large numbers of file descriptors.
> 
> njoly@lanfeust [~]> mandoc /usr/share/man/man2/select.2
> [...]
>      by providing a larger definition of FD_SETSIZE before the inclusion of
>      <sys/types.h>. The kernel will cope,and the userland libraries provided
>      with the system are also ready for large numbers of file descriptors.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Small rendering difference between nroff and mandoc

[Nicolas Joly]

On Fri, Nov 16, 2012 at 07:57:04PM +0100, Ingo Schwarze wrote:

Hello Ingo,

> Nicolas Joly wrote on Fri, Oct 12, 2012 at 05:00:36PM +0200:
> > 
> > I recently started checking for differences between nroff and mandoc
> > output for the NetBSD manpages. And noticed a small spacing difference
> > between the tools. When a sentence ends with a macro followed by a
> > punctuation mark mandoc does only output a single space character but
> > nroff adds two.
> 
> As far as i could reproduce, two particular macros were affected,
> namely .In and .Ap.  I just fixed those two in both OpenBSD and bsd.lv.
> 
> Should you find more, it would be kind if you could speak up again!

Thanks for the fix. I applied it to my local version and checked all
pages again ... A few differences remain with Cd, Fc, Fd, It(?)  and
Lb mdoc macros. Seems that some man macros show a similar behaviour,
but i'll check that part later.

Here follow the corresponding pages and constructs :

/usr/share/man/man2/intro.2
.Bl -hang -width Ds
.It Er 0 Em "Error 0" .
Not used.

/usr/share/man/man2/i386_get_ldt.2
.Fd \*[Lt]i386/segments.h\*[Gt] .
These structures are defined by the architecture

/usr/share/man/man3/math.3
.Lb libm .
Declarations for these functions may be obtained from the include file

/usr/share/man/man3/mq.3
.Lb librt .
The process scheduling interface described in

/usr/share/man/man4/pim.4
The PIM-SM protocol is specified in RFC 2362 (to be replaced by
.%T draft-ietf-pim-sm-v2-new-* ) .
The PIM-DM protocol is specified in

/usr/share/man/man7/module.7
.Cd options INSECURE .
Refer to

/usr/share/man/man8/acorn32/nbfs.8
follow RISC OS conventions,as described in the various RISC OS
.%T User Guides .
The underlying FileCore instance used by

/usr/share/man/man9/errno.9
.Bl -hang -width Ds
.It Er \-2 EJUSTRETURN Em "Modify regs, just return" .
No more work is required and the function should just return.

/usr/share/man/man9/in_getifa.9
.Cd options IPSELSRC .
.Cd options IPSELSRC
lets the operator set the policy for choosing the source address

/usr/share/man/man9/percpu.9
the CPU-local storage held by
.Fa pc ,
run
.Fo "(*cb)"
.Fa "p"
.Fa "arg"
.Fa "ci"
.Fc .
Call this in thread context.

Thanks.

-- 
Nicolas Joly

Biology IT Center
Institut Pasteur, Paris.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Small rendering difference between nroff and mandoc

[Ingo Schwarze]

Hi Nicolas,

i'm answering on the same list you posted to, but similar
reports might be more apropriate for tech@ in the future,
this stuff seems rather technical for discuss@.

Nicolas Joly wrote on Sat, Nov 17, 2012 at 11:49:54AM +0100:
> On Fri, Nov 16, 2012 at 07:57:04PM +0100, Ingo Schwarze wrote:
>> Nicolas Joly wrote on Fri, Oct 12, 2012 at 05:00:36PM +0200:

>>> I recently started checking for differences between nroff and mandoc
>>> output for the NetBSD manpages. And noticed a small spacing difference
>>> between the tools. When a sentence ends with a macro followed by a
>>> punctuation mark mandoc does only output a single space character but
>>> nroff adds two.

>> As far as i could reproduce, two particular macros were affected,
>> namely .In and .Ap.  I just fixed those two in both OpenBSD and bsd.lv.
>> 
>> Should you find more, it would be kind if you could speak up again!

> Thanks for the fix. I applied it to my local version and checked all
> pages again ... A few differences remain with Cd, Fc, Fd, It(?)  and
> Lb mdoc macros. Seems that some man macros show a similar behaviour,
> but i'll check that part later.
> 
> Here follow the corresponding pages and constructs :
> 
> /usr/share/man/man2/intro.2
> .Bl -hang -width Ds
> .It Er 0 Em "Error 0" .
> Not used.

Whoa, trailing punctuation on .It, that's likely to get ugly.
I'm not attempting to fix that in a hurry,
but instead, i'm adding a note to the TODO file.

> /usr/share/man/man2/i386_get_ldt.2
> .Fd \*[Lt]i386/segments.h\*[Gt] .
> These structures are defined by the architecture

That looks like a different issue.
Apparently, the legacy macro .Fd does not recognize trailing punctuation
and inserts an additional space *before* the final full stop.

Anyway, i fixed that one right away.

> /usr/share/man/man3/math.3
> .Lb libm .
> Declarations for these functions may be obtained from the include file
>
> /usr/share/man/man3/mq.3
> .Lb librt .
> The process scheduling interface described in

Fixed, that's indeed the same effect as in .In and .Ap.

> /usr/share/man/man4/pim.4
> The PIM-SM protocol is specified in RFC 2362 (to be replaced by
> .%T draft-ietf-pim-sm-v2-new-* ) .
> The PIM-DM protocol is specified in

Uh oh, that looks like .%T outside .Rs, which is not supposed to
occur at all and probably causes more (and maybe more serious)
problems than that.  So fixing the EOS issue only is of
questionable usefulness, and from a brief look, it doesn't
even seem easy either.

So i'm just taking a note in the TODO file for now.

> /usr/share/man/man7/module.7
> .Cd options INSECURE .
> Refer to

Fixed, again the same as .In and .Ap.
Actually, this improves wscons(4) in OpenBSD, too.

> /usr/share/man/man8/acorn32/nbfs.8
> follow RISC OS conventions,as described in the various RISC OS
> .%T User Guides .
> The underlying FileCore instance used by

Again .%T outside .Rs, i guess.

> /usr/share/man/man9/errno.9
> .Bl -hang -width Ds
> .It Er \-2 EJUSTRETURN Em "Modify regs, just return" .
> No more work is required and the function should just return.

Again .It, postponing that.

> /usr/share/man/man9/in_getifa.9
> .Cd options IPSELSRC .
> .Cd options IPSELSRC
> lets the operator set the policy for choosing the source address

Same as module(7) above, i suppose.

> /usr/share/man/man9/percpu.9
> the CPU-local storage held by
> .Fa pc ,
> run
> .Fo "(*cb)"
> .Fa "p"
> .Fa "arg"
> .Fa "ci"
> .Fc .
> Call this in thread context.

Fixed, yet again the same as .In and .Ap.

So that report yielded four small fixes immediately
and two additional TODO entries.

Thanks a lot!
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv

Re: Small rendering difference between nroff and mandoc

[Nicolas Joly]

On Sun, Nov 18, 2012 at 01:07:07AM +0100, Ingo Schwarze wrote:
> 
> i'm answering on the same list you posted to, but similar
> reports might be more apropriate for tech@ in the future,
> this stuff seems rather technical for discuss@.

Ok, will subscribe to tech@.

> So that report yielded four small fixes immediately
> and two additional TODO entries.

Thanks a lot.

-- 
Nicolas Joly

Biology IT Center
Institut Pasteur, Paris.
--
 To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv