Broken manpages constructs

Broken manpages constructs

[Ulrich Spörlein]

Hi,

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

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

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?

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\}

???

lib/libc/posix1e/acl_add_flag_np.3:55:2: FATAL: argument count wrong, violates syntax: columns == 1 (have 3)
lib/libc/posix1e/acl_add_perm.3:62:2: FATAL: argument count wrong, violates syntax: columns == 1 (have 3)
lib/libc/posix1e/acl_set_entry_type_np.3:53:2: FATAL: argument count wrong, violates syntax: columns == 1 (have 3)
lib/libc/posix1e/acl_set_tag_type.3:53:2: FATAL: argument count wrong, violates syntax: columns == 1 (have 3)
lib/libc/posix1e/acl_to_text.3:71:2: FATAL: argument count wrong, violates syntax: columns == 1 (have 3)
lib/libutil/login.conf.5:226:2: FATAL: argument count wrong, violates syntax: columns == 3 (have 5)

These all are like the first one, where there's multiple \t in the source.
groff(1) will DWIM here, btw. I can remember a time when this was not FATAL for
mandoc.

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?

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?

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?


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?

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?

share/man/man9/locking.9:298:27: FATAL: blocks badly nested: It cannot break Xo

See above

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 ...

lib/libc/sys/pathconf.2:92:2: FATAL: child violates parent syntax
lib/libc/sys/stat.2:349:1: FATAL: child violates parent syntax
sbin/fsirand/fsirand.8:77:1: FATAL: child violates parent syntax
sbin/restore/restore.8:415:2: FATAL: child violates parent syntax
share/man/man4/iscsi_initiator.4:94:2: FATAL: child violates parent syntax
share/man/man5/elf.5:466:2: FATAL: child violates parent syntax
share/man/man9/sysctl_add_oid.9:415:1: FATAL: child violates parent syntax
usr.bin/mesg/mesg.1:74:2: FATAL: child violates parent syntax
usr.sbin/mtest/mtest.8:46:2: FATAL: child violates parent syntax

Dito, more sillyness.

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 ...

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?

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

lib/libalias/libalias/../../../sys/netinet/libalias/libalias.3:208:2: FATAL: displays may not be nested

Bd inside Bl, fixed easily (was abusing Bd anyway)

lib/libc/net/nsdispatch.3:160:2: FATAL: displays may not be nested

.Dl inside .Bd, see comment about .D1

lib/msun/man/ieee.3:159:2: FATAL: displays may not be nested

151 .Bd -ragged -offset indent -compact
152 Type name:
153 .Vt float
154 .Pp
155 Wordsize: 32 bits.
156 .Pp 
157 Precision: 24 significant bits,
158 roughly like 7 significant decimals.
159 .Bd -ragged -offset indent -compact
160 If x and x' are consecutive positive single-precision
161 numbers (they differ by 1
162 .Em ulp ) , 
163 then
164 .Bd -ragged -compact
165 5.9e\-08 < 0.5**24 < (x'\-x)/x \(<= 0.5**23 < 1.2e\-07.
166 .Ed 
167 .Ed 
168 .Pp
169 .Bl -column "XXX" -compact
170 Range:»˙Overflow threshold  = 2.0**128 = 3.4e38
171 »˙˙˙˙˙˙˙Underflow threshold = 0.5**126 = 1.2e\-38 
172 .El
173 .Bd -ragged -offset indent -compact
174 Underflowed results round to the nearest
175 integer multiple of 0.5**149 = 1.4e\-45.
176 .Ed 
177 .Ed 

Just had to share this one :)

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?

usr.bin/opiekey/../../contrib/opie/opiekey.1:120:2: FATAL: line scope broken, syntax violated
usr.sbin/editmap/../../contrib/sendmail/editmap/editmap.8:100:2: FATAL: line scope broken, syntax violated

dito

usr.bin/opiepasswd/../../contrib/opie/opiepasswd.1:57:2: FATAL: line scope broken, syntax violated

 54 
 55 .SH OPTIONS
 56 .TP
 57 .TP 

Again? Is FATAL necessary here?

Fixing the rending on the manpages under contrib/ would be super-helpful, as we
cannot easily fix this at the source and other people would benefit as well.

Thanks for reading this far!

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

Re: Broken manpages constructs

[Ingo Schwarze]

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