Finish initial editorial review of Sendmail Configuration Files.

Comment out local-host-names for now until instructions for building its
needed .mc feature are added.

Sponsored by:	iXsystems

en_US.ISO8859-1/books/handbook/mail/chapter.xml

@@ -383,7 +383,7 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen>
 	right side of the table.</para>
 
       <para>Whenever this file is updated, update its database and
-	      restart <application>Sendmail</application>:</para>
+	restart <application>Sendmail</application>:</para>
 
       <screen>&prompt.root; <userinput>makemap hash /etc/mail/access &lt; /etc/mail/access</userinput>
 &prompt.root; <userinput>service sendmail restart</userinput></screen>
@@ -393,47 +393,49 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen>
     <varlistentry>
       <term><filename>/etc/mail/aliases</filename></term>
       <listitem>
-      <para>This database contains a list of virtual mailboxes that
-	are expanded to other user(s), files, programs, or other
-	aliases.  Here are a few examples to illustrate the
+      <para>This database file contains a list of virtual mailboxes that
+	are expanded to users, files, programs, or other
+	aliases.  Here are a few entries to illustrate the
 	file format:</para>
 
-      <example>
-	<title>Mail Aliases</title>
-
 	<programlisting>root: localuser
 ftp-bugs: joe,eric,paul
 bit.bucket:  /dev/null
 procmail: "|/usr/local/bin/procmail"</programlisting>
-      </example>
 
       <para>The mailbox name on the left side of the colon is expanded
 	to the target(s) on the right.  The first entry expands the
-	mailbox <systemitem class="username">root</systemitem> to the
-	mailbox <systemitem class="username">localuser</systemitem>,
-	which is then looked up again in the
-	<filename>aliases</filename> database.  If no match is found,
+	<systemitem class="username">root</systemitem> mailbox  to the
+	<systemitem class="username">localuser</systemitem> mailbox,
+	which is then looked up in the
+	<filename>/etc/mail/aliases</filename> database.  If no match is found,
 	the message is delivered to <systemitem
 	  class="username">localuser</systemitem>.  The second entry
-	shows a mail list.  Mail to the mailbox <systemitem
+	shows a mail list.  Mail to <systemitem
 	  class="username">ftp-bugs</systemitem> is expanded to the
 	three local mailboxes <systemitem
 	  class="username">joe</systemitem>, <systemitem
 	  class="username">eric</systemitem>, and <systemitem
 	  class="username">paul</systemitem>.  A remote mailbox could
-	be specified as <email>user@example.com</email>.  The third
+	be specified as <replaceable>user@example.com</replaceable>.  The third
 	entry shows how to write mail to a file, in this case
 	<filename>/dev/null</filename>.  The last entry demonstrates
 	how to send mail to a program,
 	<filename>/usr/local/bin/procmail</filename>, through a &unix;
-	pipe.</para>
+	pipe.  Refer to &man.aliases.5; for more information about the
+	format of this file.</para>
 
-      <para>Whenever this file is updated, run <command>make</command>
-	in <filename>/etc/mail/</filename> to update the
+      <para>Whenever this file is updated, run <command>newaliases</command>
+	to update and initialize the aliases
 	database.</para>
     </listitem>
     </varlistentry>
-
+<!--
+This section needs to explain that this feature is for hosts with
+alternate names, such as a host that MXs for a dynamic set of other
+hosts.
+It won't work unless freebsd.mc is built with FEATURE(`use_cw_file'),
+meaning it needs a section to refer to on how to make mc files.
     <varlistentry>
       <term><filename>/etc/mail/local-host-names</filename></term>
       <listitem>
@@ -455,7 +457,7 @@ mail.example.com</programlisting>
       restarted so that it will read the changes.</para>
   </listitem>
   </varlistentry>
-
+  -->
   <varlistentry>
     <term><filename>/etc/mail/sendmail.cf</filename></term>
     <listitem>
@@ -483,34 +485,37 @@ mail.example.com</programlisting>
   <varlistentry>
     <term><filename>/etc/mail/virtusertable</filename></term>
     <listitem>
-    <para>The <filename>virtusertable</filename> maps mail addresses
+    <para>This database file maps mail addresses
       for virtual domains and users to real mailboxes.  These
       mailboxes can be local, remote, aliases defined in
-      <filename>/etc/mail/aliases</filename>, or files.</para>
+      <filename>/etc/mail/aliases</filename>, or files.  This allows
+      multiple virtual domains to be hosted on one machine.</para>
 
-    <example>
-      <title>Example Virtual Domain Mail Map</title>
+    <para>&os; provides a sample configuration file in
+      <filename>/etc/mail/virtusertable.sample</filename> to
+      further demonstrate its format.  The following example demonstrates how
+      to create custom entries using that format:</para>
 
       <programlisting>root@example.com                root
 postmaster@example.com          postmaster@noc.example.net
 @example.com                    joe</programlisting>
-      </example>
 
-      <para>The above example contains a mapping for the domain
-	<systemitem class="fqdomainname">example.com</systemitem>.
-	This file is processed in a first match order.  The first item
-	maps <email>root@example.com</email> to the local mailbox
-	<systemitem class="username">root</systemitem>.  The second
-	entry maps <email>postmaster@example.com</email> to the
-	mailbox <systemitem class="username">postmaster</systemitem>
-	on the host <systemitem
-	  class="fqdomainname">noc.example.net</systemitem>.  Finally,
-	if nothing from <systemitem
-	  class="fqdomainname">example.com</systemitem> has matched so
-	far, it will match the last mapping, which matches every other
-	mail message addressed to someone at <systemitem
-	  class="fqdomainname">example.com</systemitem> to the local
-	mailbox <systemitem class="username">joe</systemitem>.</para>
+      <para>This file is processed in a first match order.   When an
+	email address matches the address on the left, it is mapped to
+	the local mailbox listed on the right.  The format of the first entry in
+	this example maps a specific email address to a local mailbox,
+	whereas the format of the second entry maps a specific email
+	address to a remote mailbox.  Finally, any email address
+	from <literal>example.com</literal> which has not matched any of the previous entries
+	will match the last mapping and be sent to the local mailbox
+	<literal>joe</literal>.  When creating custom entries, use
+	this format and add them to
+	<filename>/etc/mail/virtusertable</filename>.  Whenever this
+	file is edited, update its database and restart
+	<application>Sendmail</application>:</para>
+
+      <screen>&prompt.root; <userinput>makemap hash /etc/mail/virtusertable &lt; /etc/mail/virtusertable</userinput>
+&prompt.root; <userinput>service sendmail restart</userinput></screen>
     </listitem>
     </varlistentry>
   </variablelist>