Broken manpages constructs

["Ulrich Spörlein" <uqs@spoerlein.net>]

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