[RFC] Review of mount.conf man page

[Craig Rodrigues]

On Mon, Jul 8, 2013 at 2:55 PM, Benjamin Kaduk <kaduk at mit.edu> wrote:
>
>
> A few notes: our style for man pages (mdoc) is to start a new line for
new sentences.  I am not sure that the .Cm macro is appropriate to describe
.onfail and friends; I guess that devd.conf.5 is using .Ic which might be
better.  The default font for .Em is supposedly italic, so it may not be
best for the mountroot prompt, either.  I'm not sure why there are square
brackets around the 'N' argument to .timeout; does the default behavior of
3 seconds apply to a .timeout without 'N', or the absence of a .timeout?
Can you double-check whether .Pp is needed after .Ed?


I have incorporated your review comments:
(1)  replaced .Cm with .Ic
(2)  replaced .Em with .Li
(3)  remove square brackets around 'N' argument to timeout and 'file'
argument to .md
(4)  Started new sentences on new lines

I regenerated my diff and patch:

http://people.freebsd.org/~rodrigc/mount-conf/mount.conf.diff.txt
http://people.freebsd.org/~rodrigc/mount-conf/mount.conf.8.txt


Some comments:
(1)  Refer to src/sys/kern/vfs_mountroot.c, in the parse_dir_timeout()
function for the logic of how .timeout is parsed.
      If no .timeout directive is specified
      in .mount.conf, then the default timeout value will be used (3
seconds).

      If .timeout has a numerical argument, then that will set the value of
.timeout.
      If .timeout has no argument, or an argument that strtol() fails on,
then the timeout value
      will not be reset.  In that case, the timeout value will either be
the default 3 seconds,
      or if ".timeout N" was correctly specified previous to this line,
then N will be used as the timeout.

(2)  .Pp is not needed *before* .Bd, because .Bd adds vertical space.
 However .Pp *is* needed after .Ed which does
      not add vertical space afterwards.  ports.7 is one example man page
which has examples of this.

--
Craig