From owner-freebsd-doc Tue Feb 26 6:35:35 2002 Delivered-To: freebsd-doc@freebsd.org Received: from blackhelicopters.org (geburah.blackhelicopters.org [209.69.178.18]) by hub.freebsd.org (Postfix) with ESMTP id 5529737B405 for ; Tue, 26 Feb 2002 06:35:25 -0800 (PST) Received: (from mwlucas@localhost) by blackhelicopters.org (8.11.6/8.11.6) id g1QEZJO55269; Tue, 26 Feb 2002 09:35:19 -0500 (EST) (envelope-from mwlucas) Date: Tue, 26 Feb 2002 09:35:19 -0500 From: Michael Lucas To: Tom Rhodes Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/35098: [PATCH] Handbook NFS stuff Message-ID: <20020226093519.A55250@blackhelicopters.org> References: <200202231550.g1NFo1t30805@freefall.freebsd.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <200202231550.g1NFo1t30805@freefall.freebsd.org>; from darklogik@pittgoth.com on Sat, Feb 23, 2002 at 07:50:01AM -0800 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org Closer still... On Sat, Feb 23, 2002 at 07:50:01AM -0800, Tom Rhodes wrote: > + On FreeBSD, the setup of NFS is a relatively straightforward suggest ", NFS setup is relatively"; shorter. > > portmap_enable="YES" > nfs_server_enable="YES" > -nfs_server_flags="-u -t -n 4" > mountd_flags="-r" So, we're no longer giving the default flags, which is good, but you describe the options below? This will leave trailing references, where people will ask "what '-n 4' flag?" > - mountd is automatically run whenever the > - NFS server is enabled. The and > - flags to nfsd tell it to > + mountd runs automatically whenever the > + NFS server is enabled. The and > + flags tell nfsd to > serve UDP and TCP clients. The flag tells > nfsd to start 4 copies of itself. > > - nfs_client_enable="YES" > -nfs_client_flags="-n 4" > + nfs_client_enable="YES" Gratuitous whitespace; please be kind to translators. Should look more like (generated off the top of my head, not a real patch, will not apply, blah blah blah) > nfs_client_enable="YES" > -nfs_client_flags="-n 4" > + Diff size reduced by 33%, translators will appreciate it. Whoever commits this patch will re-wrap it for you. > > - Like nfsd, the tells > + As with nfsd, the tells > nfsiod to start 4 copies of itself. Ditto here on "dangling references to example that no longer exists." > + The NFS configuration requires that an > + exports file be created in the I still really dislike "be created". "be created" by what? "be", like "is", indicates passive voice. If the admin creates the file, say so. If a program creates the file, say so. We generally assume an "explicit administrator creation" throughout the docs, so this sentence could be eliminated. > + /etc directory. The /etc/exports > + file will specify which filesystems NFS should export (sometimes will specify -> specifies > > - NFS > - exporting filesystems > + Examples of exporting filesystems > So, you think this should show up in the index as "Examples of exporting filesystems" and not be referenced under NFS? That's not a very typical index entry... > - flag allows all the directories below > - the specified file system to be exported as well. > + Optionally the /etc/hosts file could be configured > + for internal hostnames, please view the &man.hosts.5; man page for more > + information. This sentence is ugly. Perhaps a semicolon instead of a comma? Also, we don't usually say "the X man page"; we just say "see X," and let the DocBook system do its magic. The flag allows for the directories > + below the specified filesystem to also be exported. "for" is unnecessary. > - Now that you have made all these changes you can just reboot > - and let FreeBSD start everything for you at boot time, or you can > - run the following commands as root: > + Alternatively, a reboot will make FreeBSD set everything > + up properly. Although, a reboot is not necessary. Never start a sentence with "although" or "however"; bad grammar. > + Executing the following commands, as root of course, "of course" is like "it goes without saying"; if it's that obvious, don't write it. And if it goes without saying, then don't say it. > system. This can be done one of two ways. In these examples the The whole "This can be done one of two ways" sentence can go entirely; it's not true. You can do temporary mounts, or automatic mounts, but they can only be done in one way. > - There are many very cool uses for NFS. Some of the more common > - ones are listed below. > + NFS has many practical. Some of the > + more common ones are listed below: Practical what? Fragment. Fragments bad. also, gratuitous whitespace. The first line in this will probably be very long, but whoever commits will word-wrap it in a second commit. > - &man.amd.8;, which is also known as the automatic mounter > - daemon, is a useful utility used for automatically mounting a > + &man.amd.8; (the automatic mounter daemon) > + is a useful utility that automatically mounts a It better be 'useful', or why are we discussing it? :-) I'd cut that bit out. "amd (the automatic mounter daemon) automatically mounts a..." ==ml -- Michael Lucas mwlucas@FreeBSD.org, mwlucas@BlackHelicopters.org my FreeBSD column: http://www.oreillynet.com/pub/q/Big_Scary_Daemons http://www.blackhelicopters.org/~mwlucas/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message