General tightening and cleanup of sections 26.1, 26.2, and 26.2.1.

- fix some acronyms along the way

The example in 26.2.1 should be changed to use callouts.

To be followed by a white space fix.

1 files changed, 105 insertions, 171 deletions

diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml
index 7cb0242e7b..8e99df307a 100644
--- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml
@@ -36,14 +36,15 @@
 
     <itemizedlist>
       <listitem>
-	<para>How to configure <acronym>PPP</acronym>.</para>
+	<para>How to configure, use, and troubleshoot a 
+	  <acronym>PPP</acronym> connection.</para>
       </listitem>
       <listitem>
 	<para>How to set up <acronym>PPP</acronym> over Ethernet
 	  (<acronym>PPPoE</acronym>).</para>
       </listitem>
       <listitem>
-	<para>How to set up <acronym>PPP</acronym> over ATM
+	<para>How to set up <acronym>PPP</acronym> over <acronym>ATM</acronym>
 	  (<acronym>PPPoA</acronym>).</para>
       </listitem>
     </itemizedlist>
@@ -106,7 +107,9 @@
 
     <title>Configuring <acronym>PPP</acronym></title>
 
-    <para>In order to configure <acronym>PPP</acronym>, the following
+    <para>&os; provides built-in support for managing dial-up
+      <acronym>PPP</acronym> connections using &man.ppp.8;.  In order
+      to use a <acronym>PPP</acronym> connection, the following
       items are needed:</para>
 
     <itemizedlist>
@@ -130,35 +133,35 @@
       </listitem>
 
       <listitem>
-	<para>The <acronym>IP</acronym> address of one or more name
-	  servers.  Normally, an <acronym>ISP</acronym> provides these
-	  addresses.  If not, use <command>enable dns</command> in
-	  <filename>ppp.conf</filename> and
-	  <application>ppp</application> will set the name servers.
-	  This feature requires the <acronym>ISP</acronym> to
-	  supporting DNS negotiation.</para>
+	<para>The <acronym>IP</acronym> address of one or more <acronym>DNS</acronym>
+	  servers.  Normally, the <acronym>ISP</acronym> provides these
+	  addresses.  If it did not, &os; can be configured to use
+	  <acronym>DNS</acronym> negotiation.</para>
       </listitem>
     </itemizedlist>
 
+    <para>If any of the required information is missing, contact
+      the <acronym>ISP</acronym>.</para>
+
     <para>The following information may be supplied by the
       <acronym>ISP</acronym>, but is not necessary:</para>
 
     <itemizedlist>
       <listitem>
 	<para>The <acronym>IP</acronym> address of the default
-	  gateway.  If this information is missing the
-	  <acronym>ISP</acronym>'s <acronym>PPP</acronym> server will
-	  provide the correct value during connection setup.</para>
-
-	<para>This <acronym>IP</acronym> number is referred to as
-	  <literal>HISADDR</literal> by
-	  <application>ppp</application>.</para>
+	  gateway.  If this information is unknown, the
+	  <acronym>ISP</acronym> will automatically
+	  provide the correct value during connection setup.  When
+	  configuring <acronym>PPP</acronym> on &os;,
+	  this address is referred to as
+	  <literal>HISADDR</literal>.</para>
       </listitem>
 
       <listitem>
 	<para>The subnet mask.  If the <acronym>ISP</acronym> has not
-	  provided one, use <hostid
-	    role="netmask">255.255.255.255</hostid>.</para>
+	  provided one, <hostid
+	    role="netmask">255.255.255.255</hostid> will be used in
+	  the &man.ppp.8; configuration file.</para>
       </listitem>
 
       <listitem>
@@ -167,35 +170,33 @@
 	</indexterm>
 
 	<para>If the <acronym>ISP</acronym> has assigned a static
-	  <acronym>IP</acronym> address and hostname, enter it.
-	  Otherwise, this information will be provided during
+	  <acronym>IP</acronym> address and hostname, it should be
+	  input into the configuration file.
+	  Otherwise, this information will be automatically provided during
 	  connection setup.</para>
       </listitem>
     </itemizedlist>
 
-    <para>If any required information is missing, contact
-      the <acronym>ISP</acronym>.</para>
+    <para>The rest of this section demonstrates how to configure &os;
+      for common <acronym>PPP</acronym> connection
+      scenarios.  The required configuration file is
+      <filename>/etc/ppp/ppp.conf</filename> and additional files and
+      examples are available in <filename
+	class="directory">/usr/share/examples/ppp/</filename>.</para>
 
     <note>
-      <para>Throughout this section, many of the examples showing the
-	contents of configuration files are numbered by line.  These
-	numbers serve to aid in the presentation and discussion only
-	and are not meant to be placed in the actual file.  Proper
-	indentation with tab and space characters is also
-	important.</para>
+      <para>Throughout this section, many of the file examples
+	display line numbers.  These line
+	numbers have been added to make it easier to follow the discussion
+	  and are not meant to be placed in the actual file.</para>  
+	    
+      <para>When editing a configuration file, proper
+	indentation is
+	important.  Lines that end in a <literal>:</literal> start in the
+	first column (beginning of the line) while all other lines
+	should be indented as shown using spaces or tabs.</para>
     </note>
 
-    <para><command>ppp</command> uses the configuration files located
-      in <filename class="directory">/etc/ppp</filename>.  Examples
-      can be found in <filename
-	class="directory">/usr/share/examples/ppp/</filename>.</para>
-
-    <para>A number of files are edited when configuring
-      <command>ppp</command>.  The edits
-      depend to some extent on whether the <acronym>ISP</acronym>
-      allocates <acronym>IP</acronym> addresses statically or
-      dynamically.</para>
-
     <sect2 id="userppp-staticIP">
       <title>PPP With Static <acronym>IP</acronym> Addresses</title>
 
@@ -205,19 +206,13 @@
 	    addresses</secondary>
       </indexterm>
 
-      <para>If the ISP has provided an address that does not change,
+      <para>If the <acronym>ISP</acronym>, also known as the peer, has provided an address that does not change,
 	edit <filename>/etc/ppp/ppp.conf</filename> as described in
 	the example below.</para>
 
-      <note>
-	<para>Lines that end in a <literal>:</literal> start in the
-	  first column (beginning of the line) while all other lines
-	  should be indented as shown using spaces or tabs.</para>
-      </note>
-
       <programlisting>1     default:
 2       set log Phase Chat LCP IPCP CCP tun command
-3       ident user-ppp VERSION (built COMPILATIONDATE)
+3       ident user-ppp VERSION
 4       set device /dev/cuau0
 5       set speed 115200
 6       set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \
@@ -229,18 +224,17 @@
 12      set phone "(123) 456 7890"
 13      set authname foo
 14      set authkey bar
-15      set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp"
-16      set timeout 300
-17      set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.255 0.0.0.0
-18      add default HISADDR</programlisting>
+15      set timeout 300
+16      set ifaddr <replaceable>x.x.x.x</replaceable>/0 <replaceable>y.y.y.y</replaceable>/0 255.255.255.255 0.0.0.0
+17      add default HISADDR</programlisting>
 
 	  <variablelist>
 	    <varlistentry>
 	      <term>Line 1:</term>
 
 	      <listitem>
-		<para>Identifies the default entry.  Commands in this
-		  entry are executed automatically when ppp is
+		<para>Identifies the <literal>default</literal> entry.  Commands in this
+		  entry (lines 2 through 9) are executed automatically when <command>ppp</command> is
 		  run.</para>
 	      </listitem>
 	    </varlistentry>
@@ -249,14 +243,12 @@
 	      <term>Line 2:</term>
 
 	      <listitem>
-		<para>Enables logging parameters.  When the
+		<para>Enables verbose logging parameters for testing the connection.  Once the
 		  configuration is working satisfactorily, this line
-		  should be reduced to saying:</para>
+		  should be reduced to:</para>
 
 		  <programlisting>set log phase tun</programlisting>
 
-		<para>in order to avoid excessive log file
-		  sizes.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -264,12 +256,9 @@
 	      <term>Line 3:</term>
 
 	      <listitem>
-		<para>Tells PPP how to identify itself to the peer.
-		  PPP identifies itself to the peer if it has any
-		  trouble negotiating and setting up the link,
-		  providing information that the peers administrator
-		  may find useful when investigating such
-		  problems.</para>
+		<para>Displays the version of &man.ppp.8; to the 
+		  <acronym>PPP</acronym> software running on the other side of the 
+		  connection.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -278,7 +267,7 @@
 
 	      <listitem>
 		<para>Identifies the device to which the modem is
-		  connected.  <devicename>COM1</devicename> is
+		  connected, where  <devicename>COM1</devicename> is
 		  <filename class="devicefile">/dev/cuau0</filename>
 		  and
 		  <devicename>COM2</devicename> is
@@ -291,26 +280,23 @@
 	      <term>Line 5:</term>
 
 	      <listitem>
-		<para>Sets the speed you want to connect at.  If
-		  115200 does not work (it should with any reasonably
-		  new modem), try 38400 instead.</para>
+		<para>Sets the connection speed.  If
+		  <literal>115200</literal> does not work on an older modem,
+		  try <literal>38400</literal> instead.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
-	      <term>Line 6 &amp; 7:</term>
+	      <term>Lines 6 &amp; 7:</term>
 
 	      <listitem>
-		<para>The dial string.  PPP uses an expect-send
-		  syntax similar to the &man.chat.8; program.  Refer
-		  to the manual page for information on the features
-		  of this language.</para>
+		<para>The dial string written as an expect-send
+		  syntax.  Refer to &man.chat.8; for more information.</para>
 
 		<para>Note that this command continues onto the next
 		  line for readability.  Any command in
 		  <filename>ppp.conf</filename> may do this if the
-		  last character on the line is a <literal>\</literal>
-		  character.</para>
+		  last character on the line is <literal>\</literal>.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -318,9 +304,7 @@
 	      <term>Line 8:</term>
 
 	      <listitem>
-		<para>Sets the idle timeout for the link.  180 seconds
-		  is the default, so this line is purely
-		  cosmetic.</para>
+		<para>Sets the idle timeout for the link in seconds.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -328,9 +312,9 @@
 	      <term>Line 9:</term>
 
 	      <listitem>
-		<para>Tells PPP to ask the peer to confirm the local
-		  resolver settings.  If you run a local name server,
-		  this line should be commented out or removed.</para>
+		<para>Instructs the peer to confirm the <acronym>DNS</acronym>
+		  settings.  If the local network is running its own <acronym>DNS</acronym> server,
+		    this line should be commented out, by adding a <literal>#</literal> at the beginning of the line, or removed.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -339,7 +323,7 @@
 
 	      <listitem>
 		<para>A blank line for readability.  Blank lines are
-		  ignored by PPP.</para>
+		  ignored by &man.ppp.8;.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -347,8 +331,8 @@
 	      <term>Line 11:</term>
 
 	      <listitem>
-		<para>Identifies an entry for a provider called
-		  <quote>provider</quote>.  This could be changed
+		<para>Identifies an entry called
+		  <literal>provider</literal>.  This could be changed
 		  to the name of the <acronym>ISP</acronym> so that
 		  <option>load
 		    <replaceable>ISP</replaceable></option> can be
@@ -360,35 +344,24 @@
 	      <term>Line 12:</term>
 
 	      <listitem>
-		<para>Sets the phone number for this provider.
+		<para>Use the phone number for the <acronym>ISP</acronym>.
 		  Multiple phone numbers may be specified using the
 		  colon (<literal>:</literal>) or pipe character
-		  (<literal>|</literal>) as a separator.  The
-		  difference between the two separators is described
-		  in &man.ppp.8;.  To summarize, to rotate
+		  (<literal>|</literal>) as a separator.  To rotate
 		  through the numbers, use a colon.  To
 		  always attempt to dial the first number first and
 		  only use the other numbers if the first number
-		  fails, use the pipe character.  Always quote the
-		  entire set of phone numbers as shown.</para>
-
-		<para>The phone number must be enclosed in quotation
-		  marks (<literal>"</literal>) if there is any
-		  intention on using spaces in the phone number.
-		  This can cause a simple, yet subtle error.</para>
-	      </listitem>
+		  fails, use the pipe character.  Always enclose the
+		  entire set of phone numbers between quotation
+		  marks (<literal>"</literal>) to prevent dialing failures.</para>
+		</listitem>
 	    </varlistentry>
 
 	    <varlistentry>
-	      <term>Line 13 &amp; 14:</term>
+	      <term>Lines 13 &amp; 14:</term>
 
 	      <listitem>
-		<para>Identifies the user name and password.  When
-		  connecting using a &unix; style login prompt, these
-		  values are referred to by the <command>set
-		    login</command> command using the \U and \P
-		  variables.  When connecting using PAP or CHAP, these
-		  values are used at authentication time.</para>
+		<para>Use the user name and password for the <acronym>ISP</acronym>.</para>
 	      </listitem>
 	    </varlistentry>
 
@@ -396,55 +369,25 @@
 	      <term>Line 15:</term>
 
 	      <listitem>
-		<para>If  <acronym>PAP</acronym> or
-		  <acronym>CHAP</acronym> are used, there will be no
-		  login at this point, and this line should be
-		  commented out or removed.  See <xref
-		    linkend="userppp-PAPnCHAP"/> for further
-		  details.</para>
-
-		<para>The login string is of the same chat-like
-		  syntax as the dial string.  In this example, the
-		  string works for a service whose login session looks
-		  like this:</para>
-
-		<screen>J. Random Provider
-login: <replaceable>foo</replaceable>
-password: <replaceable>bar</replaceable>
-protocol: ppp</screen>
-
-		<para>Alter this script to suit your
-		  own needs.  When writing this script for the first
-		  time, ensure that
-		  chat logging is enabled to help determine if
-		  the conversation is going as expected.</para>
-	      </listitem>
-	    </varlistentry>
-
-	    <varlistentry>
-	      <term>Line 16:</term>
-
-	      <listitem>
 		<para>Sets the default idle
-		  timeout<indexterm><primary>timeout</primary></indexterm>
-		  (in seconds) for the connection.  Here, the
+		  timeout
+		  in seconds for the connection.  In this example, the
 		  connection will be closed automatically after 300
-		  seconds of inactivity.  To prevent a timeout
-		  timeout, set this value to zero or use the
-		  <option>-ddial</option> command line switch.</para>
+		  seconds of inactivity.  To prevent a timeout,
+		  set this value to zero.</para>
 	      </listitem>
 	    </varlistentry>
 
 	    <varlistentry>
-	      <term>Line 17:</term>
+	      <term>Line 16:</term>
 	      <listitem>
-		<para>Sets the interface addresses.  The string
+		<para>Sets the interface addresses.  The
 		  <replaceable>x.x.x.x</replaceable> should be
-		  replaced by the <acronym>IP</acronym> address that
-		  the <acronym>ISP</acronym> has allocated.  The
-		  string <replaceable>y.y.y.y</replaceable> should be
+		  replaced by the static <acronym>IP</acronym> address that
+		  the <acronym>ISP</acronym> has allocated and the
+		  <replaceable>y.y.y.y</replaceable> should be
 		  replaced by the <acronym>IP</acronym> address of the
-		  gateway.  If the <acronym>ISP</acronym> has not
+		  default gateway.  If the <acronym>ISP</acronym> has not
 		  provided a gateway address, use <hostid
 		    role="netmask">10.0.0.2/0</hostid>.  When using a
 		  <quote>guessed</quote> address, create an entry in
@@ -456,35 +399,26 @@ protocol: ppp</screen>
 	    </varlistentry>
 
 	    <varlistentry>
-	      <term>Line 18:</term>
+	      <term>Line 17:</term>
 
 	      <listitem>
-		<para>Adds a default route to the gateway.  The
-		  special word <literal>HISADDR</literal> is replaced
-		  with the gateway address specified on line 17.  It
-		  is important that this line appears after line 17,
-		  otherwise <literal>HISADDR</literal> will not yet
-		  be initialized.</para>
-
-		<para>When <option>-auto</option> is not used, this
-		  line should be moved to the
-		  <filename>ppp.linkup</filename> file.</para>
-	      </listitem>
+		<para>Keep this line as-is as it adds a default route to the gateway.  The
+		  <literal>HISADDR</literal> will automatically be replaced
+		  with the gateway address specified on line 16.  It
+		  is important that this line appears after line 16.</para>  
+
+		  <para>When <option>-auto</option> mode is not used to start the connection, this
+		  line should be moved to
+		  <filename>ppp.linkup</filename>.  Examples for this 
+		  file can be found in <filename
+		    class="directory">/usr/share/examples/ppp/</filename>.
+		  However,
+	    <filename>ppp.linkup</filename> is not needed when running &man.ppp.8; in
+	    <option>-auto</option> mode as the routing table entries
+	    are already correct.</para>
+	     </listitem>
 	    </varlistentry>
 	  </variablelist>
-
-	  <para>It is not necessary to add an entry to
-	    <filename>ppp.linkup</filename> when using a static
-	    <acronym>IP</acronym> address and when running ppp in
-	    <option>-auto</option> mode as the routing table entries
-	    are already correct.  However, an entry can be created to
-	    invoke programs after connection.  This is explained later
-	    with the sendmail example.</para>
-
-	  <para>Example configuration files can be found in the
-	    <filename
-	      class="directory">/usr/share/examples/ppp/</filename>
-	    directory.</para>
 	</sect2>
 
 	<sect2 id="userppp-dynamicIP">
@@ -1618,19 +1552,19 @@ ppp_profile="name_of_service_provider"</programlisting>
   </sect1>
 
   <sect1 id="pppoa">
-    <title>Using <application>PPP</application> over ATM
+    <title>Using <application>PPP</application> over <acronym>ATM</acronym>
       (PPPoA)</title>
 
     <indexterm>
       <primary><acronym>PPP</acronym></primary>
-      <secondary>over ATM</secondary>
+      <secondary>over <acronym>ATM</acronym></secondary>
     </indexterm>
 
     <indexterm>
       <primary>PPPoA</primary>
     </indexterm>
 
-    <para>The following describes how to set up PPP over ATM (PPPoA).
+    <para>The following describes how to set up PPP over <acronym>ATM</acronym> (PPPoA).
       PPPoA is a popular choice among European DSL providers.</para>
 <!--
 This port is broken as of June, 2009