Date: Fri, 22 Feb 2002 10:37:16 -0500 From: Michael Lucas <mwlucas@blackhelicopters.org> To: Tom Rhodes <darklogik@pittgoth.com> Cc: freebsd-doc@FreeBSD.ORG Subject: Re: docs/35098: [PATCH] Handbook NFS stuff Message-ID: <20020222103716.A33912@blackhelicopters.org> In-Reply-To: <200202210600.g1L603b86291@freefall.freebsd.org>; from darklogik@pittgoth.com on Wed, Feb 20, 2002 at 10:00:03PM -0800 References: <200202210600.g1L603b86291@freefall.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
Tom, Much, much better. The patch has gone from the point where I can reject it at first glance, to the point where I have to actually read it in great detail to reject it. :) This means that my comments have a different character. Sorry to be picky here; the idea is to dramatically improve the language in this section. It's not enough to make the handbook better, the handbook needs to suck less. :) On Wed, Feb 20, 2002 at 10:00:03PM -0800, Tom Rhodes wrote: > + <acronym>NFS</acronym> allows your system to share directories and files It's not just your system, it's any system. It's a system. It's the system. It's systems. But not just yours. Which sounds best? (That's rhetorical, don't answer me except in patch.) > - <para>NFS has several benefits:</para> > + <para>Some benefits for using <acronym>NFS</acronym> are:</para> "benefits for using" sounds clunky. "benefits of" would be better. There are probably phrases that would be better still. Go through the various options out loud. > <listitem> > - <para>There is no need for users to have unique home directories > - on every machine on your network. Once they have an established > - directory that is available via NFS it can be accessed from > - anywhere.</para> > + <para>There would be no need for users to have unique home directories > + on every network machine. Once they have an established a home > + directory that is available on an <acronym>NFS</acronym> filesystem, > + it can be accessed from other machines on the network.</para> > </listitem> You've changed the construction of the list in this one. "There would be..." is different from the "there is" used elsewhere. (There is a proper grammatical term for this shift, but I don't care enough to go look it up at the moment.) I think what you're getting at here is that "it can be set up so..." then say it. Cleanly. > <listitem> > - <para>Storage devices such as floppies and CDROM drives can be > - used by other machines on the network eliminating the need for > - extra hardware.</para> > + <para>Storage devices such as floppy disks, CDROM drives, and ZIP drives > + can be used by other machines on the network. This may eliminate the > + need for every system to have a CDROM or ZIP drive, providing a more > + cost effective solution.</para> > </listitem> > </itemizedlist> I would say "This may reduce the number of removable media drives you need," but that's just me, since I'm commenting elsewhere. do we want to list every type of removable media? No. Do we want people to extrapolate? No. While you don't want to treat the reader like an idiot, you want to give the most precise definitions possible. > + <title>How <acronym>NFS</acronym> Works</title> > > - <para>NFS is composed of two sides – a client side and a > - server side. Think of it as a want/have relationship. The client > - <emphasis>wants</emphasis> the data that the server side > - <emphasis>has</emphasis>. The server shares its data with the > - client. In order for this system to function properly a few > - processes have to be configured and running.</para> > + <para><acronym>NFS</acronym> consists of at least two main parts: a client > + and a server. The client remotely accesses the data that is stored Perhaps "a server, and at least one client." > + <para>The client can also run a daemon, known as > + <application>nfsiod</application>. The <application>nfsiod</application> > + daemon services the requests from the <acronym>NFS</acronym> server. This > + is optional, and improves performance, but is not required for normal > + and correct operation. See the &man.nfsiod.8; man page for more information. > + </para> nfsiod is optional? (run off to man page) Well, I'll be damned, it is optional. > nfs_server_flags="-u -t -n 4" These flags are still the same as in /etc/defaults/rc.conf. They don't need to be added to /etc/rc.conf, and might in fact make life difficult if the defaults change. They shouldn't be listed here. > - <para>On the client, make sure you have:</para> > + <para>On the client, make sure these options are present in the > + <filename>/etc/rc.conf</filename> file:</para> You can cut "the" and "file". Anyone who has gotten this far knows that /etc/rc.conf is a file. See earlier comments on default settings. > - <para>The last configuration step requires that you create a file > - called <filename>/etc/exports</filename>. The exports file > - specifies which file systems on your server will be shared > - (a.k.a., <quote>exported</quote>) and with what clients they will > - be shared. Each line in the file specifies a file system to be > - shared. There are a handful of options that can be used in this > - file but only a few will be mentioned here. You can find out > - about the rest in the &man.exports.5; manual page.</para> > + <para>The <acronym>NFS</acronym> configuration requires that a file > + known as <filename>exports</filename> exist in the > + <filename>/etc</filename> directory. "The NFS configuration requires that a file known as exports exist in the /etc/ directory." Blech! Please read this sentence out loud, and then rearrange it to be easier to understand. The <filename>/etc/exports</filename> > + file specifies which filesystems on the server will be shared (or > + <firstterm>exported</firstterm>), and to which clients. Each line in NFS exports to, not "with" > + <filename>/etc/exports</filename> specifies a filesystem to be exported and > + with which this will be done. which what? ambiguous pronoun. > <para>Here are a few example <filename>/etc/exports</filename> > entries:</para> > > <indexterm> > - <primary>NFS</primary> > - <secondary>exporting filesystems</secondary> > + <primary>Examples of exporting filesystems</primary> > </indexterm> > - <para>The following line exports <filename>/cdrom</filename> to > - three silly machines that have the same domain name as the server > + > + <para>In the following examples, an idea of how to export filesystems > + is displayed, although the settings may be different depending on > + your environment and network setup. "The following examples give an idea of how to export filesystems,"... shorter, cleaner. > - shared file system.</para> > + exported file system. > + </para> Uh, gratuitous whitespace. Please make obeisances to our translators. > - private network but do not have DNS running. The > - <option>-alldirs</option> flag allows all the directories below > - the specified file system to be exported as well.</para> > + private network but do not have a <acronym>DNS</acronym> server configured. You can have DNS without having a DNS server configured. There is also /etc/hosts. Rewrite to generalize, tersely; don't need to explain the options, just need to mention name resolution. > - machines that have different domain names than the server. The > - <option>-maproot=0</option> flag allows > - the root user on the remote system to write to the shared > - file system as root. Without the -maproot=0 flag even if > - someone has root access on the remote system they will not > - be able to modify files on the shared file system.</para> > + machines with different domain names may access the filesystem. The Different than what. Perhaps "in other domains", but could be better still. > + <option>-maproot=0</option> flag allows the <username>root</username> > + user on the remote system to write data on the exported filesystem as > + <username>root</username>. If the -maproot=0 flag is not specified, then even if > + a user has <username>root</username> access on the remote system, they will not > + be able to modify files on the exported filesystem. But they can modify files. Just not as root. Fine point, there. :) > - <para>In <filename>/etc/exports</filename>, each line represents > + <para>In the <filename>/etc/exports</filename> file, each line represents I'd just use "in /etc/exports"; reader knows by now it's a file, we're pretty late in the game. > - filesystem, and you can only have one default entry per local > - filesystem. For example, let's assume that > - <filename>/usr</filename> is a single filesystem. The > - following <filename>/etc/exports</filename> is invalid:</para> > + have one entry. For example, assume that <filename>/usr</filename> > + is a single filesystem. The following <filename>/etc/exports</filename> > + would be invalid:</para> Oh, it's definitely one default entry, not just one entry. This is valid /usr client1 /usr -maproot=0 client2 /usr/ports > - <para>You must restart > - <command>mountd</command> whenever you modify > - <filename>/etc/exports</filename> to make changes take > - effect. This can be accomplished by sending the hangup signal > + <para>You must restart <command>mountd</command> whenever you modify > + <filename>/etc/exports</filename> to make the changes current. current is the wrong word > + This can be accomplished by either sending the hangup signal > to the <command>mountd</command> process:</para> "either" is the wrong word here. > + <para>Alternatively, a reboot should make FreeBSD set everything You've set it up properly. Reboot makes FreeBSD start everything properly. > + up properly if the previously described options were added to > + <filename>/etc/rc.conf</filename>. Although, a reboot is not necessary. > + Executing the following commands, as <username>root</username> of course, > + should start everything up.</para> Always assume that the reader followed your instructions. It's insulting otherwise. > > - <para>There are many very cool uses for NFS. Some of the more common > - ones are listed below.</para> > + <para>There are many practical uses for <acronym>NFS</acronym>. Some of the > + more common ones are listed below:</para> "there are" is a classic passive voice phrase, easy to eliminate when found. "NFS has many practical uses." Shorter, more direct. > + <note><para>The following <acronym>NFS</acronym> examples require > + <acronym>NFS</acronym> to be correctly configured before actual use, see > + above.</para> , see above makes the sentence clunky. "As discussed above", or "(see above)" is better. > - <para>Have several machines on a network and share a CDROM or > - floppy drive among them. This is cheaper and often more > - convenient.</para> > + <para>Set up several machines on a network to share a CDROM or > + floppy drive among them. This is cheaper and often more convenient.</para> > </listitem> Of course they're on a network. Excess wordage. Also, gratuitous whitespace. Your initial patch will make the line shorter, but ...often more convenient.<para> is easier for our translators. Your committer will fix whitespace in a separate commit. > <listitem> > - <para>With so many machines on a network, it gets old having your > - personal files strewn all over the place. You can have a > - central NFS server that houses all user home directories and > - shares them with the rest of the machines on the LAN, so no > - matter where you log in you will have the same home > - directory.</para> > + <para>On large networks, it may be more convenient to configure a Get a dictionary. :) may=permission might=possibility > + central <acronym>NFS</acronym> server in which to store all the user > + home directories on. "on" is unnecessary. > + <para>You can use one CDROM on the <acronym>NFS</acronym> server to install > + FreeBSD over the network on multiple machines.</para> > </listitem> I don't like this sentence, but I'm not sure why. > <listitem> > - <para>Have a common <filename>/usr/ports/distfiles</filename> > - directory that all your machines share. That way, when you go > - to install a port that you have already installed on a different > - machine, you do not have to download the source all over > - again!</para> > + <para>Several machines could have a common <filename>/usr/ports/distfiles</filename> > + directory, assuming of course all the machines are FreeBSD. Last comment unnecessary. I share /usr/ports/distfiles to Solaris and AIX boxes; source code is source code is source code. At times I need a port on a Solaris box, and don't want to re-download the program when it's over on the FreeBSD box. Tools, not policy. > - <para>&man.amd.8;, which is also known as the automatic mounter > - daemon, is a useful utility used for automatically mounting a > + <para>&man.amd.8; (the automatic mounter daemon) > + is a useful utility used for automatically mounting a "that automatically mounts" faster, cleaner, terser. -- 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020222103716.A33912>