Quick review requested

Jim Brown jpb at sixshooter.v6.thrupoint.net
Wed Oct 1 00:36:41 UTC 2003


* Tom Rhodes <trhodes at FreeBSD.org> [2003-09-30 18:03]:
> Gang,
> 
> I'd really appreciate some feedback on the text below.  If anyone
> would like the full patch (images, Makefile, etc) please speak up
> and I'll send it.
> 
> Whitespace in added text will be fixed before the initial cvs ci,
> so comments on short/long lines are not required.
> 
> Thanks!
> 
> -- 
> Tom Rhodes
> 


Comments inline- sorry.  I don't have my doc stuff set up on this system
so I can't check what it looks like visually.



> --- doc.old/en_US.ISO8859-1/books/handbook/install/chapter.sgml	Mon Sep 29 13:40:57 2003
> +++ doc/en_US.ISO8859-1/books/handbook/install/chapter.sgml	Mon Sep 29 18:39:26 2003
> @@ -3382,6 +3382,233 @@
>  	post-installation configuration.</para>
>      </sect2>
>  
> +    <sect2 id="network-services">
> +      <title>Configure Additional Network Services</title>
> +
> +      <para>Configuring the network services can be a daunting
> +	task for new users if they lack any previous network configuration knowledge.
> +	Configuring a network
> +	is an important aspect of &os;, therefore users should at least
> +	have an understanding of various services available to them.</para>

"Configuring the network..." followed by "configuration" followed by "Configuring the network.."
is somewhat repetitive.  Can you choose a different word or make it flow
a bit better?  Also '... the network ...' followed by '... a netowrk ...' seemed
to clash for me.  Might be just too much coffee though.




> +
> +      <para>Selecting the <quote>Networking</quote> option will bring forth a menu
> +	similar to the one below:</para>

s/bring forth/display/
seems a bit better to me.


> +
> +      <figure id="network-configuration">
> +	<title>Network Configuration Upper-level</title>
> +
> +	<mediaobject>
> +	  <imageobject>
> +	    <imagedata fileref="install/net-config-menu1" format="PNG">
> +	  </imageobject>
> +	</mediaobject>
> +      </figure>
> +
> +      <para>The first option, Interfaces, was previously covered during
> +	the Network Device Configuration section; thus we can bypass
> +	this option.</para>

You are in the first person here.



> +
> +      <para>Selecting the <option>AMD</option> option adds
> +	support for the <acronym>BSD</acronym> auto mount utility.
> +	This is usually used in conjunction with the
> +	<acronym>NFS</acronym> protocol (see below)
> +	for automatically mounting remote file systems.
> +	No special configuration
> +	is required here.</para>
> +
> +      <para>Next in line is the <acronym>AMD</acronym> flags
> +	option.  When selected, a menu will pop up for you
> +	to enter specific <acronym>AMD</acronym> flags.
> +	The menu already contains a set of default options:</para>
> +
> +      <screen>-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map</screen>
> +
> +      <para>The <literal>-a</literal> option specifies the default mount
> +	location which is listed here as <filename>/.amd_mnt</filename>.
> +	The <literal>-l</literal> option specifies the default
> +	<filename>log</filename> file; however, when &man.syslogd.8; is

I would use <literal>syslog</literal> here.  The option should never look
like 'syslog(8)'.  Might confuse a newbie.


> +	specified all log activity will be sent to the system log daemon.
> +	The <filename>/host</filename> is used to mount an exported
> +	file system from a remote hostname, while
> +	<filename>/net</filename> is used to mount an exported file
> +	system from an <acronym>IP</acronym> address.  The
> +	<filename>/etc/amd.map</filename> defines the default options
> +	for <acronym>AMD</acronym> exports.</para>
> +
> +      <para>The Anon <acronym>FTP</acronym> should be
> +	self explanatory.  Select this option to permit anonymous

If I'm a newbie, I won't know what is self explanatory.  I would offer:
"<para>The Anon <acronym>FTP</acronym> option permits anonymous ..."
or something similar.


> +	<acronym>FTP</acronym> logins.  Be aware of the security risks
> +	involved with this option.  Another menu will be displayed to
> +	explain the security risks and configuration in depth.</para>
> +
> +      <para>The <option>Gateway</option> configuration menu will set
> +	the machine up to be a gateway as explained previously.  This
> +	can be used to unset the gateway option if you accidentally
> +	selected it during the installation process.</para>
> +
> +      <para>The <option>Inetd</option> option can be used to configure or
> +	completely disable the &man.inetd.8; daemon as discussed above.</para>
> +
> +      <para>The <option>Mail</option> is used to configure the system's
> +	default <acronym>MTA</acronym> or mail server.  Selecting this
> +	option will bring forth the following menu:</para>
> +
> +      <figure id="mta-selection">
> +	<title>Select a default MTA</title>
> +
> +	<mediaobject>
> +	  <imageobject>
> +	    <imagedata fileref="install/mta-main" format="PNG">
> +	  </imageobject>
> +	</mediaobject>
> +      </figure>
> +
> +      <para>Here the user is given a choice as to which
> +	<acronym>MTA</acronym>, or Mail Transfer Agent to install
> +	and set as the default.  An <acronym>MTA</acronym> is nothing
> +	more than a mail server which delivers email to users on the
> +	system or the Internet.</para>
> +
> +      <para>Selecting <application>Sendmail</application> will install
> +	the popular <application>Sendmail</application> server which
> +	is the &os; default.  The <option>Sendmail local</option> option
> +	will set <application>Sendmail</application> to be the default
> +	<acronym>MTA</acronym>, but disables its ability to receive
> +	incoming email from the Internet.  The other options here,
> +	<application>Postfix</application> and
> +	<application>Exim</application> act similar to
> +	<application>Sendmail</application>, as in they both deliver

"as in they both" doesn't work for me.  Perhaps:

"<application>Sendmail</application>. They both deliver ..."


> +	email; however, selecting either of these is more of a user
> +	preference than anything else.</para>
> +
> +      <para>After selecting an <acronym>MTA</acronym>, or choosing
> +	not to select an MTA, we are back at the default menu with

First person.  See note at end.


> +	the next option being <acronym>NFS</acronym> client.</para>
> +
> +      <para>The <acronym>NFS</acronym> client will
> +	set the machine to work as a client for an
> +	<acronym>NFS</acronym> server.  An <acronym>NFS</acronym> server
> +	exports remotely mounted file systems to other machines on the local
> +	network via the <acronym>NFS</acronym> protocol.  If this is
> +	a stand alone machine, this option can remain unselected.  The
> +	system may require more configuration later, see
> +	<xref linkend="network-nfs"> for more
> +	information about client and server configuration.</para>
> +
> +      <para>Below that option is the
> +	<acronym>NFS</acronym> server option,
> +	permitting a user to set the system up as an
> +	<acronym>NFS</acronym> server.  This adds the required
> +	information to start up the <acronym>RPC</acronym> remote
> +	procedure call services.  <acronym>RPC</acronym> is used to
> +	coordinate connections between hosts and programs.</para>
> +
> +      <para>Next in line is the <option>Ntpdate</option> option,
> +	which deals with time synchronization.  When selected, a menu
> +	like the one below shows up:</para>
> +
> +      <figure id="Ntpdate-config">
> +	<title>Ntpdate Configuration</title>
> +
> +	<mediaobject>
> +	  <imageobject>
> +	    <imagedata fileref="install/ntp-config" format="PNG">
> +	  </imageobject>
> +	</mediaobject>
> +      </figure>
> +
> +      <para>From this menu, select the server which is the closest
> +	to your location.  Selecting a close one will make the time
> +	synchronization more accurate as a server further from your
> +	location may have more connection latency.</para>
> +
> +      <para>Our next option is the
> +	<acronym>PCNFSD</acronym> selection.  This
> +	option will install the
> +	<filename role="package">net/pcnfsd</filename> package from
> +	the ports collection.  This is a useful utility which provides
> +	<acronym>NFS</acronym> authentication services for systems which
> +	are unable to provide their own.  For instance, Microsoft's
> +	<acronym>DOS</acronym> operating system.</para>
> +
> +      <para>Now we must scroll down a bit to see the other options:</para>
> +
> +      <figure id="Network-configuration-cont">
> +	<title>Network Configuration Lower-level</title>
> +
> +	<mediaobject>
> +	  <imageobject>
> +	    <imagedata fileref="install/net-config-menu2" format="PNG">
> +	  </imageobject>
> +	</mediaobject>
> +      </figure>
> +
> +      <para>The &man.rpcbind.8;, &man.rpc.statd.8;, and
> +	&man.rpc.lockd.8; utilities are all used for Remote Procedure
> +	Calls (<acronym>RPC</acronym>).  The <command>rpcbind.8</command>
> +	utility handles the communication between <acronym>NFS</acronym>
> +	servers, their clients, and is required for
> +	<acronym>NFS</acronym> servers to operate correctly.  The
> +	<command>rpc.statd</command> daemon interacts with the
> +	<command>rpc.statd</command> daemon on other hosts to provide
> +	status monitoring.  The reported status is usually held in the
> +	<filename>/var/db/statd.status</filename> file.  The final
> +	option listed here is the <command>rpc.lockd</command> option,
> +	which, when selected, will provide for file locking.  This is
> +	usually used with <command>rpc.statd</command> to monitor what
> +	hosts are requesting locks and how frequent they request them.
> +	While these last two options are marvelous for debugging, they
> +	are not required for <acronym>NFS</acronym> servers and clients
> +	to operate correctly.</para>
> +
> +      <para>As we progress down the list the next item here is
> +	<option>Routd</option>, which is the route daemon.  The

Is the option really 'Routd' or 'Routed'?  I don't have a way to check
this at the moment.

> +	&man.routed.8; utility manages the network routing tables,
> +	discovers multicast routers, and supplies a copy of the routing
> +	tables to any physically connected host on the network upon
> +	request.  This is mainly used for routing
> +	<quote>connectionless</quote> protocols (see &man.icmp.4 and
> +	&man.udp.4;).  When selected, a menu will be presented
> +	requesting the default location of the utility.  The default
> +	location is already defined for you and can be selected with
> +	the <keycap>Enter</keycap> key.  You will then be presented
> +	with yet another menu, this time asking for the flags you wish
> +	to be passed on to <command>routed</command>.  The default is
> +	<literal>-q</literal> and it should already appear on the
> +	screen.</para>
> +
> +      <para>Next in line is the <option>Rwhod</option> option which,
> +	when selected, will have the &man.rwhod.8; daemon start up
> +	during system initialization.  The <command>rwhod</command>
> +	utility broadcasts system messages across the network
> +	periodically, or collects them when in <quote>consumer</quote>
> +	mode.  This utility is great for monitoring the status of
> +	machines on the network, but can be highly annoying when in
> +	<quote>producer mode</quote> as it will broadcast messages
> +	every three minutes or so.</para>
> +
> +      <para>Next to the last option in the list we have the

Usually seen as:

<para>The next to last option in the list we have the ...



> +	&man.sshd.8; daemon.  This is the secure shell server for
> +	<application>OpenSSH</application> and it is highly recommended
> +	over the standard <command>telnet</command> and
> +	<acronym>FTP</acronym> servers.  The <command>sshd</command>
> +	server is used to create a secure connection from one host to
> +	another by using encryption connections.</para>

s/encryption/encrypted/
seems better to me.


> +
> +      <para>Finally there is the <acronym>TCP</acronym> Extensions
> +	option.  This enables the <acronym>TCP</acronym> Extensions
> +	as defined by <acronym>RFC</acronym> 1323 and
> +	<acronym>RFC</acronym> 1644.  While on many hosts this can
> +	speed up connections, but can also cause some connections to

s/but/it/
seems better to me.


> +	or be dropped.  It is not recommended for servers but may be

s/or//


> +	beneficial for stand alone machines.</para>
> +
> +      <para>Now that we have configured the network services, we can
> +	scroll up to the very top item which is <option>Exit</option>
> +	and continue on to the next configuration section.</para>
> +
> +    </sect2>
> +
>      <sect2 id="x-server">
>        <title>Configure X Server</title>


General Note:

The text fluctuates between first, second, and third  person- sometimes in
close proximity.  You may wish to review this as it causes an unnecessary
shift in perspective for the reader.


Quite a good effort overall.

As always all comments meant with Best Regards,

jpb
===




More information about the freebsd-doc mailing list