Date: Mon, 04 Mar 2002 02:03:04 -0500 From: Tom Rhodes <darklogik@pittgoth.com> To: Giorgos Keramidas <keramida@freebsd.org>, Michael Lucas <mwlucas@blackhelicopters.org>, freebsd-doc@freebsd.org Subject: Re: docs/35098: [PATCH] Handbook NFS stuff Message-ID: <3C831C28.2050006@pittgoth.com> References: <200202262110.g1QLA2f07435@freefall.freebsd.org> <20020302152507.A83170@blackhelicopters.org> <20020302230131.GA99866@hades.hell.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
Giorgos Keramidas wrote: < snip some junk :) > > >> <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> >> + on every network machine. Home directories could be setup on the >> + <acronym>NFS</acronym> server and made available throughout the network.</para> >> </listitem> >> > >I'd probably go for "There is no need for users to have separate ..." here. >'Unique' is almost exclusively used when a reference to a set of objects is >made, and emphasis on their being different is needed. > This was not really an easy one to understand, after reading it over and over again with both words, I did an append here. The quick s/unique/separate/ took no real time and i'm going to whip up another patch for you ;) > > >> <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 reduce the number >> + of removable media drives.</para> >> > >Number of 'required' or 'necessary' media drives? >Whose number of media drives? > Added: throughout the network at the very end here, to me it sounds better "of removable media drives throughout the network" > > >> + <para><acronym>NFS</acronym> consists of at least two main parts: a server >> + and at least one client. The client remotely accesses the data that is stored >> + on the server machine. In order for this to function properly a few >> + processes have to be configured and running:</para> >> > >Whitespace nit. If you use tab for initial line indentation, please use it >consistently, before commiting this; since this replaces the entire >paragraph, it doesn't count as a 'whitespace only change'. > Done :) were right in check now! > > >> + <entry> The portmapper daemon >> + allows <acronym>NFS</acronym> clients to discover which port the <acronym>NFS</acronym> server >> + is using.</entry> >> > >Whitespace nit. Since this is an entirely new <entry>, could we have it >properly indented and wrapped too? (For some definition of 'properly' that >fits the style of the rest of this document.) > I see what you mean, and like above, this has been corrected in patch number 5 :) > > >> + <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. >> > >s/man page/manual page/ > >This is not some doc-policy style of thing, but I tend to prefer one of >these two forms: > > * The &blah; manual page. > > * You can find out by checking out &man.blah; how this is done. > >I'm not really that sure about this though. It's really up to you two to >decide if you like one of these two any better. > I think this convention should be a doc standard, as it would be best to keep all the manual page refereances similar, it sounds bad when you have one person in chapter 3 say "check the man page" and someone in chapter 7 say "please review the manual page" Which sounds more realistic to you? I will take number 2 personally :) Perhaps whoever is working on the primer, if anyone, could add this to it, along with the no underscores in man entitys (ie: &man.pkg_add.1; is NO while &man.pkg.add.1; is YES) Whileist that person is at it, we could also use some info on the <sgmltag> option. I know that we have a few other tags not listed there, but I just cannot think of any at 01:30 EST :) > >> + <para><command>mountd</command> runs automatically whenever the >> + <acronym>NFS</acronym> server is enabled. >> > >Indentation needs fix0ring, and there's a missing </para>. > More proof that I have been working to hard latly :( diff(1) here I come! > > >> <programlisting>nfs_client_enable="YES" >> -nfs_client_flags="-n 4"</programlisting> >> - >> - <para>Like <command>nfsd</command>, the <option>-n 4</option> tells >> - <command>nfsiod</command> to start 4 copies of itself.</para> >> + </programlisting> >> > >Should we close </programlisting> on the first and 'last' line of content? > > <programlisting>nfs_client_enable="YES"</programlisting> > I have seen times where it was right at the closing on the next line, and on the current line. Because I was removing some text I did not really wish to remove the entire line. In my patch this has been changed, if mw lucas does not like it, than he can newline it upon the initial commit. ;) > > >> + <para> >> + The <filename>/etc/exports</filename> >> ... >> + that can be used in this file but only a few will be mentioned here. You can easily discover >> + other options by reading over the &man.exports.5; manual page. >> + </para> >> > >Please indent a bit, wrap the replacement paragraph to some reasonable >length, and make <para>...</para> cuddle to the text within, at the >beginning and end of it, like the rest of the text does: > > <para>... > ...</para> > >> + <para>The following examples give an idea of how to export filesystems, >> + although the settings may be different depending on >> + your environment and network configuration. >> + The following line exports <filename>/cdrom</filename> to >> + three example machines that have the same domain name as the server >> > >I'm a little uncomfortable with two sentences that both start with 'The >following'. The second could probably be rewritten as: > > For instance, to export <filename>/cdrom</filename> ... > Here I did: "For instance, to export the <filename>/cdrom</filename> directory to three example machines" I did not use "mount point" as I really did not wish to confuse anyone :) > > >> + <para>The following line exports <filename>/a</filename> so that two >> + clients from different domains may access the filesystem. The >> + <option>-maproot=0</option> flag allows the <username>root</username> >> + user on the remote system to write data on the exported filesystem as >> > >That same tab vs. space thing for initial indentation, again :-/ > >Since there are many places where tabs and spaces have been mixed in >indentation, I'll probably shuttup now. > >> + <para>The &man.fstab.5; manual page lists all the available options.</para> >> > >Wheeeee :) >"The &foo; manual page." :) >Thanks, thanks! > >> + <para>Set several machines to share a CDROM or >> + other media among them. This is cheaper and often >> + more convenient.</para> >> > >Than what? > reworded to: "This is a cheaper and often a more convenient method to install software on multiple machines" keeping the current "mutiple machines" term, and providing an understandable idea. Hopefully this extra line will get the gears turning in our readers mind about other uses. > > >> + <para>Several machines could have a common <filename>/usr/ports/distfiles</filename> >> > >wrap? > >[-- Finally --] > >Excellent work! I haven't used NFS in a while, and I am probably not the >best guy to comment on technical parts of this, but it looks great. Very >easy to follow, IMHO. > Good ;) I think thats the goal here. > > >My apologies, if commenting now is a bit late, and has you thinking things >like 'Ya, right, Mr. Anal Retentiveness, where were you when we were >writing this stuff?'. I seem to have a complete lack of organization in >my time schedule these last weeks, and I keep forgetting TODO stuff. > >Cheers, > To be honest, I will be the first to admit that free time is not always availible when I want it. Better late than never. I hope you will enjoy this new patch ;) -- Tom Rhodes 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?3C831C28.2050006>