Re: Broken manpages constructs

[Ingo Schwarze <schwarze@usta.de>]

Hi Ulrich,

> Ingo (more or less) requested a list of manpages on FreeBSD that break
> with mandoc, i.e., mandoc dies, no output at all.

Yes, looking at such things is potentially useful, thanks.

> I think this is simply the list of manpages where -Tlint gives FATAL
> errors, correct?

Correct for current mandoc (1.10.6).

In case you just want the FATALs, you can say

  find ... -print0 | xargs -0 mandoc -Tlint -Wfatal

By default, -Tlint is -Tlint -Wall, but you can override that,
just as no -T is -Tascii is -Tascii -Wfatal by default,
which you can override as well.


> Here we go, short comments as to what shall be done are appreciated!
> 
> bin/ps/ps.1:295:2: FATAL: argument count wrong, violates syntax: columns == 2 (have 4)
> 
> 287 .Bl -column P_SINGLE_BOUNDARY 0x40000000
> 288 .It Dv "P_ADVLOCK" Ta No "0x00001»????????????Process may hold a POSIX advisory lock"
> 289 .It Dv "P_CONTROLT" Ta No "0x00002»??????????Has a controlling terminal"
> 290 .It Dv "P_KTHREAD" Ta No "0x00004»????????????Kernel thread"
> 291 .It Dv "P_PPWAIT" Ta No "0x00010»??????????????Parent is waiting for child to exec/exit"
> 292 .It Dv "P_PROFIL" Ta No "0x00020»??????????????Has started profiling"
> 293 .It Dv "P_STOPPROF" Ta No "0x00040»??????????Has thread in requesting to stop prof"
> 294 .It Dv "P_HASTHREADS" Ta No "0x00080»??????Has had threads (no cleanup shortcuts)"
> 295 .It Dv "P_SUGID" Ta No "0x00100»»??????????????Had set id privileges since last exec"
> 
> Here, »???? denotes a tab-character, so on the last line, there's two tabs to
> make the input aligned. mandoc thinks this is another column. Why is this
> FATAL?

That's on my list to turn into an ERROR, there is no need for mandoc
to give up.

That said, i think mandoc is right to throw an ERROR.
Usually, having at least two more columns in the table
than were declared in the table header indicates that
something is seriously garbled, and output formatting
is likely to end up far from the author's intent.

Even though P_SUGID is shorter than seven characters,
formatters ought to get the alignment right without a double tab.
I think you should remove one of the tabs.
It still formats correctly with groff and mandoc after that, right?


> gnu/usr.bin/patch/patch.1:64:2: FATAL: argument count wrong, violates syntax: line arguments == 0 (have 1)
> 
>  58 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
>  59 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
>  60 .ds L" ""
>  61 .ds R" ""
>  62 .ds L' '
>  63 .ds R' '
>  64 'br \}
>  65 .el \{\
>  66 .ds -- \(em\|
>  67 .tr \*(Tr
>  68 .ds L" ``
>  69 .ds R" ''
>  70 .ds L' `
>  71 .ds R' '
>  72 'br\}
> 
> ???

That's on my list to turn into an ERROR, there is no need for mandoc
to give up.

On top of that, it looks like a bug in the mandoc roff parser.
The roff parser should consume the "\}" brace closing the if instruction
and not pass it as an argument to the .br macro.

I'm adding this to
  http://mdocml.bsd.lv/cgi-bin/cvsweb/TODO?rev=HEAD&cvsroot=mdocml


[...]
> usr.bin/ee/../../contrib/ee/ee.1:10:2: FATAL: argument count wrong, violates syntax: line arguments <= 5 (have 6)
> 
>  10 .TH ee 1 "" "" "" ""
>  11 .SH NAME
>  12 ee \- easy editor
> 
> Yeah, well. It's contributed code and so far my attempts to contact Hugh have
> been in vain :/ But still, a FATAL error?

That's on my list to turn into an ERROR, there is no need for mandoc
to give up.


> lib/libc/rpc/rpc_soc.3:398:22: FATAL: blocks badly nested: It cannot break Xo
> 
>  396 .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
>  397 .It Dv CLSET_TIMEOUT Ta Xo
>  398 .Vt "struct timeval" Ta "set total timeout"
>  399 .Xc
>  400 .It Dv CLGET_TIMEOUT Ta Xo
>  401 .Vt "struct timeval" Ta "get total timeout"
>  402 .Xc
>  403 .El
> 
> Will this ever be supported?

It is on the TODO list:

  - .Bl -column .Xo support is missing

But it is hard and not likely to happen just tomorrow.
Kristaps is afraid of trying to implement that,
and i know very little about mandoc phrase code.

  .Bl -column "CLSET_RETRY_TIMEOUT" "struct sockaddr_in"
  .It Dv CLSET_TIMEOUT Ta Vt "struct timeval" Ta "set total timeout"
  .It Dv CLGET_TIMEOUT Ta Vt "struct timeval" Ta "get total timeout"
  .El

ought to work with both mandoc and groff.


> lib/msun/man/math.3:84:2: FATAL: blocks badly nested: El cannot break Ss
> 
>  74 .de Cl
>  75 .Bl -column "isgreaterequal" "bessel function of the second kind of the order 0"
>  76 .Em "Name»????????????Description"
>  77 ..
>  78 .Ss Algebraic Functions
>  79 .Cl
>  80 cbrt»??????cube root
>  81 fma»????????fused multiply-add
>  82 hypot»????Euclidean distance
>  83 sqrt»??????square root
>  84 .El
>  85 .Ss Classification Macros
>  86 .Cl
>  87 fpclassify»??????????classify a floating-point value
> 
> This is due to a custom define,
> is/will this be supported, or is it too low-level roff?

It is on the TODO list:

  - implement basic non-parametric .de

That's perhaps even easier than it might seem,
but i don't consider it very high priority,
it's probably not the next item from the list
that will get picked up.


> sbin/setkey/setkey.8:445:2: FATAL: blocks badly nested: It cannot break Bd
> 
> 444 .Bd -ragged -offset indent
> 445 .It Fl P Ar direction Li discard
> 446 .It Fl P Ar direction Li none
> 447 .It Xo Fl P Ar direction Li ipsec
> 448 .Ar protocol/mode/src-dst/level Op ...
> 449 .Xc
> 450 .Ed
> 
> Again the Xo/Xc issue?

Hm, .It outside .Bl, not that easy to make that non-FATAL.

This looks like part of a SYNOPSIS.  Neither .Bd nor .It have
a place in that kind of a context.  I guess this should be
rewritten from scratch, this code looks syntactically and
semantically wrong in so many respects.


> share/man/man4/ulpt.4:60:1: FATAL: blocks badly nested: It cannot break Do
> 
>  58 .Bl -column "Minor Bit" "Functionxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -offset indent
>  59 .Em "Minor Bit»??Function"
>  60 64»??????????Do not initialize (reset) the device on the port.
>  61 .El
> 
> This one is nice, read carefully, the second column starts with Do and mandoc
> will interpret this as .Do, this can perhaps be worked around by using \&Do or
> similarly silly constructs. Any better ideas?

I should probably turn that into an ERROR and make the .It
implicitely close out the .Do.

That said, i don't think modern groff (1.17 or later) will not
format this as intended by the author, either.

The "Do" must be escaped, and "\&Do" is not silly, but the standard
way to prevent macro interpretation.


[...]
> lib/libc/sys/getpriority.2:133:1: FATAL: child violates parent syntax
> 
> 132 .Bl -tag -width Er
> 133 In addition to the errors indicated above,
> 134 .Fn setpriority
> 135 will fail if:
> 136 .It Bq Er EPERM
> 
> Ok, this one is obvious, I wonder how people came up with this ...

Yes, but we are planning to turn it into an ERROR, anyway.
.Bl can just assume an implicit .It "" and be done with it.


[...]
> sbin/ipfw/ipfw.8:1013:2: FATAL: child violates parent syntax
> 
> 1011 .It Ar addr : Oo Cm not Oc Bro
> 1012 .Bl -tag -width indent
> 1013 .Cm any | me | me6 |
> 1014 .Cm table Ns Pq Ar number Ns Op , Ns Ar value
> 1015 .Ar | addr-list | addr-set 
> 1016 .Brc
> 
> That's probably a tough one ...

Hm, too little context, so i can't say whether mandoc could cope.

I guess this is nested lists?
The inner list lacking .It?
On top of that, in a SYNOPSIS?
Should probabably be rewritten from scratch.


> bin/sh/sh.1:569:2: FATAL: displays may not be nested
> 
>  567 .Bd -unfilled -offset indent
>  568 .Oo Ar n Oc Ns Li << Ar delimiter
>  569 .D1 Ar here-doc-text
>  570 .D1 ...
>  571 .Ar delimiter
>  572 .Ed
> 
> Can we haz D1 inside Bd/Ed please?

I have a very old diff somewhere, but don't think it will still apply.
Even though mdoc.samples(7) explicitely disallows nested displays,
i don't see why we shouldn't support it, it is not hard, and even
if we don't recommend it, some people have used it in the past.

Adding it to the TODO list...


> kerberos5/usr.bin/kadmin/../../../crypto/heimdal/kadmin/kadmin.8:163:2: FATAL: displays may not be nested
> 
> 147 .Bd -ragged -offset indent
> 148 .Nm add
> 149 .Op Fl r | Fl -random-key
> 150 .Op Fl -random-password
> 151 .Oo Fl p Ar string \*(Ba Xo
> 152 .Fl -password= Ns Ar string
> 153 .Xc
> 154 .Oc
> ...
> 162 .Pp
> 163 .Bd -ragged -offset indent
> 164 Adds a new principal to the database. The options not passed on the
> 165 command line will be promped for.
> 166 .Ed
> 167 .Pp
> 
> No comment

Looks like a runaway .Bd, completely forgotten .Ed, right?

When we allow nested displays, the whole page might end up
in that display...  :)


> sbin/ipf/ippool/../../../contrib/ipfilter/man/ippool.5:61:2: FATAL: line scope broken, syntax violated
> 
>  58 .PP
>  59 At this point in time, only IPv4 addressing is supported.
>  60 .TP
>  61 .SH OVERVIEW
>  62 .PP
>  63 The IP pool configuration file provides for defining two different mechanisms
> 
> FATAL error because of TP before SH? Is that really necessary?

No, that should be a mere WARNING, i think;
on my list to clean up FATALs, anyway.


[...]
> Thanks for reading this far!

  *grin*  dto.

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