From owner-freebsd-arch@FreeBSD.ORG Sat Jul 13 22:33:23 2013 Return-Path: Delivered-To: freebsd-arch@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 17D82EBB; Sat, 13 Jul 2013 22:33:23 +0000 (UTC) (envelope-from crodr001@gmail.com) Received: from mail-lb0-x22f.google.com (mail-lb0-x22f.google.com [IPv6:2a00:1450:4010:c04::22f]) by mx1.freebsd.org (Postfix) with ESMTP id 665FA122E; Sat, 13 Jul 2013 22:33:22 +0000 (UTC) Received: by mail-lb0-f175.google.com with SMTP id r10so8345219lbi.6 for ; Sat, 13 Jul 2013 15:33:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:sender:in-reply-to:references:date :x-google-sender-auth:message-id:subject:from:to:cc:content-type; bh=aNfBWinDJxcoQeqOlf69jfScnlp172BfMBZWmCH/69g=; b=XmLNyQNGJNP7nO5Dda20OGTXVuY9421Vtj+9/e1SX2pCp4e3NtrH/0xdRoGln0aTUG /wsyYk4d7O+cUnVqKNP8ee9n78VabyVWKoN3jtWUJZjBrVAaCmgodHoPxmWipvtICcX4 YPi/69KLtGVjLOlCwhm87C1rXB9Fsu62+em95KN6eaARHec6Rvw9ysG3L6BzgIZjiJW0 51fCsPwf/VLFObKAKDwrmSuMry3TizmfH+nibUM0lJpZtiRqERLngmjfIsDEE3c+I2tz /G8B94LRLWQEf6gzpzhF2HgHI8+rnWgUrIOiA1/CZENr0/fPmmpctBBzsTeuSQcRbCIm QVRA== MIME-Version: 1.0 X-Received: by 10.152.4.65 with SMTP id i1mr22012115lai.21.1373754801358; Sat, 13 Jul 2013 15:33:21 -0700 (PDT) Sender: crodr001@gmail.com Received: by 10.112.149.38 with HTTP; Sat, 13 Jul 2013 15:33:21 -0700 (PDT) In-Reply-To: References: Date: Sat, 13 Jul 2013 15:33:21 -0700 X-Google-Sender-Auth: hgbRuvHZ6_dKYvZF-wyB1ETgXaI Message-ID: Subject: Re: [RFC] Review of mount.conf man page From: Craig Rodrigues To: Benjamin Kaduk Content-Type: text/plain; charset=ISO-8859-1 X-Content-Filtered-By: Mailman/MimeDel 2.1.14 Cc: Marcel Moolenaar , freebsd-arch@freebsd.org X-BeenThere: freebsd-arch@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion related to FreeBSD architecture List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 13 Jul 2013 22:33:23 -0000 On Mon, Jul 8, 2013 at 2:55 PM, Benjamin Kaduk 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