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?
    htmlmdoc
  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?
    htmlmdoc
  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.
    htmlmdoc
  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:
    htmlmdoc
    There are still three problems with it. How could it be improved further?

htmlmdoc
September 29, 2015 bsd.lv