PROBLEMS(MDOC) MDOC PROBLEMS(MDOC)

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

  1. The iscsictl(8) manual in the NetBSD 6.1.5 release contains the following source code:
    .Bl -tag width xdxsockdirx 
    .It Fl d Ar sockdir 
    Specify the directory where the socket for 
    .Xr iscsid 8 
    lives. 
    .El
        
    What's wrong with that? How was it fixed?
    html — mdoc
  2. The fopen(3) manual in the NetBSD 6.1.5 release contains the following source code (abbreviated):
    .Bl -bullet -offset 2n 
    .It Sq x 
    The letter 
    .Sq x 
    in the mode turns on exclusive open mode to the file ( 
    .Dv O_EXCL ) 
    which means that the file will not be created if it already exists. 
    .El
        
    Which problems exist with this code? How can they be fixed?
    html — mdoc
  3. The mount(2) manual in the FreeBSD 10.1 release contained the following source code:
    The following options are required by all file systems: 
    .Bl -item -offset indent -compact 
    .It 
    .Li fstype Ta file system type name (e.g., Dq Li procfs ) 
    .It 
    .Li fspath Ta mount point pathname (e.g., Dq Li /proc ) 
    .El
        
    What's wrong with that? Propose better markup.
    html — mdoc
  4. Once you have decided how you would fix it, look at what was actually committed for FreeBSD 10.2; here is the current version in FreeBSD 11:
    html — mdoc
    There are still three problems with it. How could it be improved further?

html — mdoc
September 29, 2015 bsd.lv