.Dd September 29, 2015
.Dt PROBLEMS MDOC
.Os
.Sh NAME
.Nm structure/solutions/problems
.Nd structural markup bugs in real-world BSD manuals
.Sh SOLUTIONS
.Bl -enum
.It
All keyword arguments to structural macros start with a dash.
Here, the dash is missing before
.Fl width .
.Pp
The corrected version in NetBSD 7.0 looks like this:
.Bd -literal -offset indent
\&.Bl -tag -width xdxsockdirx
\&.It Fl d Ar sockdir
Specify the directory where the socket for
\&.Xr iscsid 8
lives.
\&.El
.Ed
.Pp
.Lk ../../examples/NetBSD-7.0/iscsictl.html html
\(em
.Lk ../../examples/NetBSD-7.0/iscsictl.mdoc mdoc
.It
A
.Fl bullet
list does not allow arguments to the
.Ic \&It
macro, so the
.Ql \&Sq x
argument is lost.
.Pp
Besides, automatic suppression of spacing after an opening delimiter
doesn't work if there is an input line break in between,
so a blank character is printed between the opening parenthesis and
.Dv O_EXCL .
.Pp
For NetBSD 7.0, all this was properly fixed as follows:
.Bd -literal -offset indent
\&.Bl -tag -width 4n
\&.It Sq x
The letter
\&.Sq x
in the mode turns on exclusive open mode to the file
\&.Pq Dv O_EXCL
which means that the file will not be created if it already exists.
\&.El
.Ed
.Pp
.Lk ../../examples/NetBSD-7.0/fopen.html html
\(em
.Lk ../../examples/NetBSD-7.0/fopen.mdoc mdoc
.It
One problem is that
.Ic \&Ta
macros are only allowed in
.Ic \&Bl Fl column
lists, not on
.Ic \&It
lines of other list types.
For FreeBSD 10.2, the block line was changed as follows:
.Pp
.Dl .Bl -column fstype -offset indent
.Pp
That's clearly an improvement.
.It
For better robustness, each line of the table should be on one single
.Ic \&It
input line, without intervening input line breaks.
.Pp
Besides, the table is using a lot of physical markup with the
.Ic \&Li
macro.
Probably, semantic macros like
.Ic \&Ic ,
.Ic \&Cm ,
and
.Ic \&Pa
should be used instead, as follows:
.Bd -literal -offset indent
The following options are required by all file systems:
\&.Bl -column fstype -offset indent
\&.It Ic fstype Ta file system type name (e.g., Cm procfs )
\&.It Ic fspath Ta mount point pathname (e.g., Pa /proc )
\&.El
.Ed
.Pp
That would results in:
.Bl -column fstype -offset indent
.It Ic fstype Ta file system type name (e.g., Cm procfs )
.It Ic fspath Ta mount point pathname (e.g., Pa /proc )
.El
.El