PROBLEMS(MDOC) MDOC PROBLEMS(MDOC)

structure/solutions/problems
structural markup bugs in real-world BSD manuals

  1. All keyword arguments to structural macros start with a dash. Here, the dash is missing before -width.
    The corrected version in NetBSD 7.0 looks like this:
    .Bl -tag -width xdxsockdirx 
    .It Fl d Ar sockdir 
    Specify the directory where the socket for 
    .Xr iscsid 8 
    lives. 
    .El
        
    htmlmdoc
  2. A -bullet list does not allow arguments to the It macro, so the ‘Sq x’ argument is lost.
    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 O_EXCL.
    For NetBSD 7.0, all this was properly fixed as follows:
    .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
        
    htmlmdoc
  3. One problem is that Ta macros are only allowed in Bl -column lists, not on It lines of other list types. For FreeBSD 10.2, the block line was changed as follows:
    .Bl -column fstype -offset indent
    That's clearly an improvement.
  4. For better robustness, each line of the table should be on one single It input line, without intervening input line breaks.
    Besides, the table is using a lot of physical markup with the Li macro. Probably, semantic macros like Ic, Cm, and Pa should be used instead, as follows:
    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
        
    That would results in:
    file system type name (e.g., procfs)
    mount point pathname (e.g., /proc)
September 29, 2015 bsd.lv