Symbols and troff conditionals

Symbols and troff conditionals

[Ulrich Spörlein]

Hi folks,

some errors while linting manpages:

.Dd June 9, 2010
.Dt TITLE 1
.Os
.Sh NAME
.Nm test
.Nd test
.Sh SYNOPSIS
foo
.Sh DESCRIPTION
Testing symbols like \(+-\*(Pi or
\(-> fails somehow.
Also, conditionals when used like this
.if n \{\
do
.\}
.if t \{\
do not
.\}
complain.


% mandoc -Tlint test.1
test.1:10:22: bad escape sequence
test.1:11:1: bad escape sequence
test.1:15:1: request scope close w/none open
test.1:18:1: request scope close w/none open

What's up with the \(-> and \(+- symbols?

Also, the end-of-conditional detection seems to need some improvement.
This form is occurring at several places in our manpages ...

Regards,
Uli
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Symbols and troff conditionals

[Kristaps Dzonsons]

> Testing symbols like \(+-\*(Pi or
> \(-> fails somehow.

Oi, this one was a real head-scratcher for a few minutes.  Great find!
And fixed.
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Symbols and troff conditionals

[Kristaps Dzonsons]

> Also, conditionals when used like this
> .if n \{\
> do
> .\}
> .if t \{\
> do not
> .\}
> complain.

Also fixed, but please let me know if this is puking in different ways
on your manpages, as it was in kind of a tricksy place.

Thanks again,

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Symbols and troff conditionals

[Ulrich Spörlein]

On Wed, 09.06.2010 at 22:11:52 +0200, Kristaps Džonsons wrote:
> > Also, conditionals when used like this
> > .if n \{\
> > do
> > .\}
> > .if t \{\
> > do not
> > .\}
> > complain.
> 
> Also fixed, but please let me know if this is puking in different ways
> on your manpages, as it was in kind of a tricksy place.

Hey Kristaps, the other fix is fine, this fix however is a
regression, though :(
It now barfs on some other conditionals, here's a real life sample:

.Dd June 9, 2010
.Dt TITLE 1
.Os
.Sh NAME
.Nm test
.Nd test
.Sh SYNOPSIS
foo
.Sh DESCRIPTION
Testing symbols like \(+-\*(Pi or
\(-> fails somehow.
Also, conditionals when used like this
.if n \{\
do
.\}
.if t \{\
do not
.\}
complain.
lib/msun/atan2.3 has also these kinds of conditionals:
The
.Fn atan2
function is used mostly to convert from rectangular (x,y)
to polar
.if n\
(r,theta)
.if t\
(r,\(*h)
coordinates that must satisfy x =
.if n\
r\(**cos theta
.if t\
r\(**cos\(*h
and y =
.if n\
r\(**sin theta.
.if t\
r\(**sin\(*h.
These equations are satisfied when (x=0,y=0)
is mapped to
.if n \
(r=0,theta=0).
.if t \
(r=0,\(*h=0).
In general, conversions to polar coordinates
should be computed thus:



% groff -Tascii -mandoc /tmp/test.1
TITLE(1)                FreeBSD General Commands Manual               TITLE(1)

NAME
     test -- test

SYNOPSIS
     foo

DESCRIPTION
     Testing symbols like +-pi or -> fails somehow.  Also, conditionals when
     used like this do complain.  lib/msun/atan2.3 has also these kinds of
     conditionals: The atan2() function is used mostly to convert from rectan-
     gular (x,y) to polar (r,theta) coordinates that must satisfy x = r*cos
     theta and y = r*sin theta.  These equations are satisfied when (x=0,y=0)
     is mapped to (r=0,theta=0).  In general, conversions to polar coordinates
     should be computed thus:

FreeBSD 8.1                      June 9, 2010                      FreeBSD 8.1
% ./mandoc /tmp/test.1
TITLE(1)                    General Commands Manual                   TITLE(1)

NAME
     test -- test

SYNOPSIS
     foo

DESCRIPTION
     Testing symbols like +-pi or -> fails somehow.  Also, conditionals when
     used like this do complain.  lib/msun/atan2.3 has also these kinds of
     conditionals: The atan2() function is used mostly to convert from
     rectangular (x,y) to polar coordinates that must satisfy x = theta theta.
     is mapped to (r=0,theta=0).  In general, conversions to polar coordinates
     should be computed thus:

FreeBSD 8.1-PRERELEASE           June 9, 2010           FreeBSD 8.1-PRERELEASE
% ./mandoc -Tlint /tmp/test.1
/tmp/test.1:27:2: unknown macro will be lost: unknown macro: if
(1)% mandoc -Tlint /tmp/test.1          # (this is mandoc 1.10.1)
/tmp/test.1:10:22: bad escape sequence
/tmp/test.1:11:1: bad escape sequence
/tmp/test.1:15:1: request scope close w/none open
/tmp/test.1:18:1: request scope close w/none open

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

Re: Symbols and troff conditionals

[Kristaps Dzonsons]

Hi Ulrich, these aren't really regressions, but rather unsupported 
behaviour.  mandoc(1) isn't smart enough to do full conditional 
evaluation, so, and I'll note it in the file...

> .if n\
> (r,theta)
> .if t\
> (r,\(*h)

after line concatenation looks like

.if n(r,theta)
.if t(r,\(*h)

to mandoc, which subsequently barfs because it reads conditionals as 
text up until space or eoln.  So the conditional is "n(r,theta)", which 
is true as "n" is first, but obviously there's no body except for the 
subsequent "if".

I'll see if I can get some intelligence into this.

Thanks again for the reports!

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv

Re: Symbols and troff conditionals

[Kristaps Dzonsons]

Kristaps Dzonsons wrote:
> Hi Ulrich, these aren't really regressions, but rather unsupported 
> behaviour.  mandoc(1) isn't smart enough to do full conditional 
> evaluation, so, and I'll note it in the file...
> 
>> .if n\
>> (r,theta)
>> .if t\
>> (r,\(*h)
> 
> after line concatenation looks like
> 
> .if n(r,theta)
> .if t(r,\(*h)
> 
> to mandoc, which subsequently barfs because it reads conditionals as 
> text up until space or eoln.  So the conditional is "n(r,theta)", which 
> is true as "n" is first, but obviously there's no body except for the 
> subsequent "if".

Ok, I made it a tad bit smarter.  Now, from roff.7:

      COND is a conditional statement.  roff allows for complicated
      conditionals; mandoc is much simpler.  At this time, mandoc
      supports only `n', evaluating to true; and `t', `e', and `o',
      evaluating to false.  All other invocations are read up to the
      next end of line or space and evaluate as false.

Thus, the `n' is correctly parsed, in your example, and it spits out the 
correct manual.  I added a regression test to this effect.

Thanks,

Kristaps
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv