Date: Sun, 3 Mar 2002 01:01:32 +0200 From: Giorgos Keramidas <keramida@freebsd.org> To: Michael Lucas <mwlucas@blackhelicopters.org> Cc: Tom Rhodes <darklogik@pittgoth.com>, freebsd-doc@freebsd.org Subject: Re: docs/35098: [PATCH] Handbook NFS stuff Message-ID: <20020302230131.GA99866@hades.hell.gr> In-Reply-To: <20020302152507.A83170@blackhelicopters.org> References: <200202262110.g1QLA2f07435@freefall.freebsd.org> <20020302152507.A83170@blackhelicopters.org>
next in thread | previous in thread | raw e-mail | index | archive | help
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 2002-03-02 15:25, Michael Lucas wrote:
> Okay, I think I'm done ripping on this poor guys work. Anything left
> for me to say is purely stylistic.
Tom has been doing a lot of work, lately.
Michael, you've also carefully checked what he posted, and usually have
already commented already by the time I downloaded the thread.
My compliments, guys :)
You certainly make everyone envy you^W^W^H proud.
> <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.
> <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?
> + <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'.
> + <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.)
> + <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.
> + <para><command>mountd</command> runs automatically whenever the
> + <acronym>NFS</acronym> server is enabled.
Indentation needs fix0ring, and there's a missing </para>.
> <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>
> + <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> ...
> + <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?
> + <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.
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,
Giorgos Keramidas FreeBSD Documentation Project
keramida@{freebsd.org,ceid.upatras.gr} http://www.FreeBSD.org/docproj/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (FreeBSD)
iD8DBQE8gVnL1g+UGjGGA7YRAnn9AJ4g/baYxyLTAcvNbIrhY8oCfQM2vACfSOe8
PEySyVyLUJX6dhmufV3y7+c=
=bzKC
-----END PGP SIGNATURE-----
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?20020302230131.GA99866>