Added coverage of news, clarified POP/IMAP distinction (there's a theme to

2000-09-01  Aaron Weber  <aaron@helixcode.com>

	* C/config-prefs.sgml: Added coverage of news, clarified POP/IMAP
	distinction (there's a theme to these four log entries here).

	* C/usage-mail.sgml: Added coverage of news.

	* C/config-setupassist.sgml: Revised mail sources content for
	IMAP/POP stuff.

	* C/apx-gloss.sgml: Added IMAP and POP.

svn path=/trunk/; revision=5166

8 files changed, 272 insertions, 94 deletions

diff --git a/doc/C/apx-gloss.sgml b/doc/C/apx-gloss.sgml
index 5693ecda1c..f13a56106a 100644
--- a/doc/C/apx-gloss.sgml
+++ b/doc/C/apx-gloss.sgml
@@ -173,14 +173,27 @@
   </glossdef>
  </glossentry> 
 
-
+ <glossentry id="imap">
+  <glossterm>IMAP</glossterm>
+  <glossdef>
+   <para>
+    Depending upon whom you ask, IMAP stands for the Internet Mail
+    Access Protocol, or the Interim Mail Access Protocol.  Whatever it
+    stands for, it allows access to email which is typically (although
+    not always) stored remotely on a server rather than on a local
+    hard disk.  Often contrasted with <glossterm>POP</glossterm>.
+    This will not be on the test.
+   </para>
+  </glossdef>
+ </glossentry>
+ 
   <glossentry id="ldap">
    <glossterm>LDAP</glossterm>
    <glossdef>
     <para>
-     LDAP is a protocol which allows a client to search through a large database
-     of addresses, phone numbers, and people, as an alternative to a physical
-     phone book.
+     LDAP is a protocol which allows a client to search through a
+     large database of addresses, phone numbers, and people, as an
+     alternative to a physical phone book.
     </para>
    </glossdef>
   </glossentry>
@@ -227,6 +240,17 @@
   </glossdef>
  </glossentry>
 
+ <glossentry id="pop">
+  <glossterm>POP</glossterm>
+  <glossdef>
+   <para>
+     POP, the Post Office Protocol, is a mechanism for email
+     transport.  In contrast to IMAP, it is used only to get mail from
+     a server and store it locally on your hard disk.
+   </para>
+  </glossdef>
+ </glossentry>
+
  <glossentry id="regular-expression">
   <glossterm>Regular Expression</glossterm>
   <glossdef>
diff --git a/doc/C/config-prefs.sgml b/doc/C/config-prefs.sgml
index e0f6dd0297..997868ca2f 100644
--- a/doc/C/config-prefs.sgml
+++ b/doc/C/config-prefs.sgml
@@ -215,6 +215,15 @@
 	    </varlistentry>
 	  </variablelist>
           </para>
+          <para>
+            If you choose several mail sources, clicking
+            <guibutton>Get Mail</guibutton> will refresh any IMAP or
+            <filename>mbox</filename> listings and check and download
+            all POP servers.  In other words, <guibutton>Get
+            Mail</guibutton> gets your mail, no matter how many
+            sources you have, or what types they are.
+          </para>
+
       </sect3>
       <sect3 id="config-prefs-mail-network-transports">
 	<title>Transports</title>
@@ -226,7 +235,7 @@
            which uses the <application>sendmail</application> program
            on your local system.  <application>Sendmail</application>
            is more difficult to configure, but offers more flexibility
-           than plain <systemitem>SMTP</systemitem>.
+           than <systemitem>SMTP</systemitem>.
         </para>
 	<para>
             To use <guilabel>SMTP</guilabel>, you'll need to enter the
@@ -234,30 +243,30 @@
             <userinput>smtp.isp.net</userinput>.
          </para>
          <para>
-            <application>Evolution</application> can
-            attempt to determine if you have entered the right server
-            name.  To have it do so, check the box labelled
-            <guilabel>Test these values before continuing</guilabel>
-            before you click <guibutton>OK</guibutton>.
+            <application>Evolution</application> can attempt to
+            determine if you have entered a valid server name.  To
+            have it do so, check the box labelled <guilabel>Test these
+            values before continuing</guilabel> before you click
+            <guibutton>OK</guibutton>.
          </para>
 	</sect3>
       </sect2>
-      <sect2 id="config-prefs-network-news">
-
- <!-- WHY is this in the MAIL config section? WHY is this UI SOOOO bad?-->
-          
+      <sect2 id="config-prefs-network-news">          
           <title>News Servers</title>
           <para>
+            Newsgroups are so much like mailing lists that there's no
+            reason not to have access to them right next to your mail.
             When you first select the <guilabel>News
             Servers</guilabel> tab, you will see a blank box with
             three familiar buttons on the right:
             <guibutton>Add</guibutton>, <guibutton>Edit</guibutton>,
-            and <guibutton>Delete</guibutton>.
-          </para>  
+            and <guibutton>Delete</guibutton>.  </para>
           <para>
             Click <guibutton>Add</guibutton> to add a news server; you
             will be prompted for its name.  Enter the name, click
-            <guibutton>OK</guibutton>, and you're done. (FIXME, this needs work).
+            <guibutton>OK</guibutton>, and you're done.  You can have
+            as many mail servers as you like, of course.  News servers
+            will appear next to your IMAP servers.
           </para>
      </sect2>
 
diff --git a/doc/C/config-setupassist.sgml b/doc/C/config-setupassist.sgml
index 52ca546b9a..8355f90f90 100644
--- a/doc/C/config-setupassist.sgml
+++ b/doc/C/config-setupassist.sgml
@@ -83,11 +83,22 @@
 	  <listitem>
 	    <para>
               <application>Evolution</application> supports three mail
-              sources: POP servers, the most common email server type;
-              IMAP, which stores mail remotely and allows access from
-              multiple locations, and UNIX-style
-              <filename>mbox</filename> files.  Ask your system
-              administrator which one you use.
+              sources: <glossterm>POP</glossterm> servers,
+              <glossterm>IMAP</glossterm> servers, and UNIX-style
+              <filename>mbox</filename> files.  POP servers retrieve
+              your mail and store it on your local system so you can
+              refer to it even when not connected to a network;
+              <glossterm>IMAP</glossterm> servers store the mail on
+              the server so you can access it from multiple locations;
+              UNIX-style <filename>mbox</filename> files are used by
+              your computer for internal mail, and may be useful if
+              you want to switch from another email client such as
+              <application>spruce</application> or
+              <application>mutt</application>.  Ask your system
+              administrator which you should use, or keep guessing
+              until one works.  You may use multiple servers if you
+              wish; see <xref linkend="config-prefs-mail-network"> for
+              more information.
             </para>
 	  </listitem>
 	  </varlistentry>
diff --git a/doc/C/usage-mail.sgml b/doc/C/usage-mail.sgml
index ad7419f330..5dfa03d8c1 100644
--- a/doc/C/usage-mail.sgml
+++ b/doc/C/usage-mail.sgml
@@ -25,7 +25,8 @@
        <listitem>
 	 <para>
 	   It supports multiple mail sources, including IMAP, POP3,
-	   and local <filename>mbox</filename> files.
+	   local <filename>mbox</filename> files, and even NNTP data
+	   (newsgroups), which isn't technically email.
 	 </para>
        </listitem>
      </itemizedlist>
@@ -150,40 +151,68 @@
           message to message.
         </para>
       </sect3>
+      <sect3 id="usage-mail-getnsend-delete">
+        <title>Deleting Mail</title>
+        <para>
+          To delete a message, select it in the the <interface>message
+          list</interface> by clicking on it once.  Then click on the
+          <guibutton>Delete</guibutton> button in the tool bar.  The
+          message now has a line through it, because you've marked it
+          for deletion. 
+        </para>
+        <para>
+          If you really want to get rid of it, choose
+          <guimenuitem>Expunge</guimenuitem> from the
+          <guimenu>Actions</guimenu> menu.  That will delete it
+          permanently. If you want to keep it, click
+          <guibutton>Delete</guibutton> again, and it will no longer
+          be marked as deleted.  At some point in the future, this
+          feature will change to something a little less
+          counter-intuitive.
+        </para>
+      </sect3>
     </sect2>
 
     <sect2 id="usage-mail-getnsend-get">
       <title>Checking Mail</title>
-
       <para>
 	Now that you've had a look around the
-	<interface>Inbox</interface>, select the welcome message in
-	the <interface>message list</interface> by clicking on it
-	once.  Then click on the <guibutton>Delete</guibutton> button
-	in the tool bar.  The message now has a line through it,
-	because you've marked it for deletion.  If you really want to
-	get rid of it, choose <guimenuitem>Expunge</guimenuitem> from
-	the <guimenu>Actions</guimenu> menu.  That will delete it
-	permanently. If you want to keep it, click
-	<guibutton>Delete</guibutton> again, and it will no longer be
-	marked as deleted.  At some point in the future, this feature
-	will change to something a little less counter-intuitive.
+	<interface>Inbox</interface>, it's time to check for new mail.
+	Before you get it, though, you should decide where you want to
+	keep it.  Your options will vary a little depending on your
+	network setup, but they come down to storing the mail on your
+	hard disk (using <glossterm>POP</glossterm>), or storing it on
+	the network (using <glossterm>IMAP</glossterm>).  If you store
+	your mail on your local hard disk, you can read it whether
+	you're online or not, but you can only read it from one
+	computer.  If you store it on the network, you can only read
+	it when you're online, but you can access it from almost any
+	computer with a network connection, even if it doesn't have
+	<application>Evolution</application>.
+      </para>
+      <para>
+        If you choose POP, you'll be putting mail in the
+        <guilabel>Inbox</guilabel> in the <guilabel>Local</guilabel>
+        folder.  If you choose IMAP, it's the
+        <guilabel>Inbox</guilabel> of a folder with the same name as
+        your mail server.  That's so you can maintain several distinct
+        IMAP servers if you want.  See <xref
+        linkend="config-prefs-mail"> for more information about mail
+        servers.
       </para>
-
-
       <para>
-	To check your email, just click <guibutton>Get
-	mail</guibutton> in the toolbar.  If this is the first time
-	you've done so, the <interface>mail setup
+        Regardless of where you keep your mail, you can click
+	<guibutton>Get mail</guibutton> in the toolbar to check your
+	mail.  The first time you do that, the <interface>mail setup
 	assistant</interface> will ask you for the information it
 	needs to check your mail (see <xref
 	linkend="config-setupassist"> for more information).  If
 	you're checking mail over a network (instead of from local
 	<filename>mbox</filename> files), you'll need to enter your
-	email password.  Type it in, click <guibutton>OK</guibutton> and
-	<application>Evolution</application> will download your mail.
-	New mail will appear in your <interface>Inbox</interface>.
-	<!-- FIXME: add mention of Today if Today feature appears -->
+	email password.  Type it in, click <guibutton>OK</guibutton>
+	and <application>Evolution</application> will download your
+	mail.  New mail will appear in your
+	<interface>Inbox</interface>.
       </para>
       <para>
         Once you've entered your password,
@@ -206,6 +235,22 @@
 	linkend="config-prefs-mail-network">, or ask your system
 	administrator.
       </para>
+      
+      <sect3 id="usage-mail-getnsend-get-news">
+         <title>Using Evolution for News </title>
+       <para>
+         Newsgroups are so similar to email there's no reason not to
+         read them side by side.  If you want to do that, add a news
+         source to your configuration (see <xref
+         linkend="config-prefs-network-news">). The news server will
+         appear as a remote server, and will look exactly like an IMAP
+         folder, except that you can't delete messages from it.  When
+         you click <guibutton>Get Mail</guibutton>,
+         <application>Evolution</application> will also check for news
+         messages.  If you prefer to use a different program, there's
+         always <application>Pan</application>.
+       </para>
+       </sect3>
 
       <sect3 id="usage-mail-getnsend-get-attach">
 	<title>Attachments, HTML Mail, and Live Documents</title>
@@ -284,9 +329,9 @@
 	   Evolution will send mail immediately unless you tell it to
 	   do otherwise by selecting <menuchoice>
 	   <guimenu>File</guimenu> <guimenuitem>Send
-	   Later</guimenuitem></menuchoice>.  That will add messages to the
-	   <guilabel>Outbox</guilabel> queue.  Then, when you press
-	   <guibutton>Send</guibutton> in another message, or
+	   Later</guimenuitem></menuchoice>.  That will add messages
+	   to the <guilabel>Outbox</guilabel> queue.  Then, when you
+	   press <guibutton>Send</guibutton> in another message, or
 	   <guibutton>Get Mail</guibutton> in the main mail window,
 	   all your unsent messages will go out at once.  I like to
 	   use "Send Later" because it gives me a chance to change my
diff --git a/help/C/apx-gloss.sgml b/help/C/apx-gloss.sgml
index 5693ecda1c..f13a56106a 100644
--- a/help/C/apx-gloss.sgml
+++ b/help/C/apx-gloss.sgml
@@ -173,14 +173,27 @@
   </glossdef>
  </glossentry> 
 
-
+ <glossentry id="imap">
+  <glossterm>IMAP</glossterm>
+  <glossdef>
+   <para>
+    Depending upon whom you ask, IMAP stands for the Internet Mail
+    Access Protocol, or the Interim Mail Access Protocol.  Whatever it
+    stands for, it allows access to email which is typically (although
+    not always) stored remotely on a server rather than on a local
+    hard disk.  Often contrasted with <glossterm>POP</glossterm>.
+    This will not be on the test.
+   </para>
+  </glossdef>
+ </glossentry>
+ 
   <glossentry id="ldap">
    <glossterm>LDAP</glossterm>
    <glossdef>
     <para>
-     LDAP is a protocol which allows a client to search through a large database
-     of addresses, phone numbers, and people, as an alternative to a physical
-     phone book.
+     LDAP is a protocol which allows a client to search through a
+     large database of addresses, phone numbers, and people, as an
+     alternative to a physical phone book.
     </para>
    </glossdef>
   </glossentry>
@@ -227,6 +240,17 @@
   </glossdef>
  </glossentry>
 
+ <glossentry id="pop">
+  <glossterm>POP</glossterm>
+  <glossdef>
+   <para>
+     POP, the Post Office Protocol, is a mechanism for email
+     transport.  In contrast to IMAP, it is used only to get mail from
+     a server and store it locally on your hard disk.
+   </para>
+  </glossdef>
+ </glossentry>
+
  <glossentry id="regular-expression">
   <glossterm>Regular Expression</glossterm>
   <glossdef>
diff --git a/help/C/config-prefs.sgml b/help/C/config-prefs.sgml
index e0f6dd0297..997868ca2f 100644
--- a/help/C/config-prefs.sgml
+++ b/help/C/config-prefs.sgml
@@ -215,6 +215,15 @@
 	    </varlistentry>
 	  </variablelist>
           </para>
+          <para>
+            If you choose several mail sources, clicking
+            <guibutton>Get Mail</guibutton> will refresh any IMAP or
+            <filename>mbox</filename> listings and check and download
+            all POP servers.  In other words, <guibutton>Get
+            Mail</guibutton> gets your mail, no matter how many
+            sources you have, or what types they are.
+          </para>
+
       </sect3>
       <sect3 id="config-prefs-mail-network-transports">
 	<title>Transports</title>
@@ -226,7 +235,7 @@
            which uses the <application>sendmail</application> program
            on your local system.  <application>Sendmail</application>
            is more difficult to configure, but offers more flexibility
-           than plain <systemitem>SMTP</systemitem>.
+           than <systemitem>SMTP</systemitem>.
         </para>
 	<para>
             To use <guilabel>SMTP</guilabel>, you'll need to enter the
@@ -234,30 +243,30 @@
             <userinput>smtp.isp.net</userinput>.
          </para>
          <para>
-            <application>Evolution</application> can
-            attempt to determine if you have entered the right server
-            name.  To have it do so, check the box labelled
-            <guilabel>Test these values before continuing</guilabel>
-            before you click <guibutton>OK</guibutton>.
+            <application>Evolution</application> can attempt to
+            determine if you have entered a valid server name.  To
+            have it do so, check the box labelled <guilabel>Test these
+            values before continuing</guilabel> before you click
+            <guibutton>OK</guibutton>.
          </para>
 	</sect3>
       </sect2>
-      <sect2 id="config-prefs-network-news">
-
- <!-- WHY is this in the MAIL config section? WHY is this UI SOOOO bad?-->
-          
+      <sect2 id="config-prefs-network-news">          
           <title>News Servers</title>
           <para>
+            Newsgroups are so much like mailing lists that there's no
+            reason not to have access to them right next to your mail.
             When you first select the <guilabel>News
             Servers</guilabel> tab, you will see a blank box with
             three familiar buttons on the right:
             <guibutton>Add</guibutton>, <guibutton>Edit</guibutton>,
-            and <guibutton>Delete</guibutton>.
-          </para>  
+            and <guibutton>Delete</guibutton>.  </para>
           <para>
             Click <guibutton>Add</guibutton> to add a news server; you
             will be prompted for its name.  Enter the name, click
-            <guibutton>OK</guibutton>, and you're done. (FIXME, this needs work).
+            <guibutton>OK</guibutton>, and you're done.  You can have
+            as many mail servers as you like, of course.  News servers
+            will appear next to your IMAP servers.
           </para>
      </sect2>
 
diff --git a/help/C/config-setupassist.sgml b/help/C/config-setupassist.sgml
index 52ca546b9a..8355f90f90 100644
--- a/help/C/config-setupassist.sgml
+++ b/help/C/config-setupassist.sgml
@@ -83,11 +83,22 @@
 	  <listitem>
 	    <para>
               <application>Evolution</application> supports three mail
-              sources: POP servers, the most common email server type;
-              IMAP, which stores mail remotely and allows access from
-              multiple locations, and UNIX-style
-              <filename>mbox</filename> files.  Ask your system
-              administrator which one you use.
+              sources: <glossterm>POP</glossterm> servers,
+              <glossterm>IMAP</glossterm> servers, and UNIX-style
+              <filename>mbox</filename> files.  POP servers retrieve
+              your mail and store it on your local system so you can
+              refer to it even when not connected to a network;
+              <glossterm>IMAP</glossterm> servers store the mail on
+              the server so you can access it from multiple locations;
+              UNIX-style <filename>mbox</filename> files are used by
+              your computer for internal mail, and may be useful if
+              you want to switch from another email client such as
+              <application>spruce</application> or
+              <application>mutt</application>.  Ask your system
+              administrator which you should use, or keep guessing
+              until one works.  You may use multiple servers if you
+              wish; see <xref linkend="config-prefs-mail-network"> for
+              more information.
             </para>
 	  </listitem>
 	  </varlistentry>
diff --git a/help/C/usage-mail.sgml b/help/C/usage-mail.sgml
index ad7419f330..5dfa03d8c1 100644
--- a/help/C/usage-mail.sgml
+++ b/help/C/usage-mail.sgml
@@ -25,7 +25,8 @@
        <listitem>
 	 <para>
 	   It supports multiple mail sources, including IMAP, POP3,
-	   and local <filename>mbox</filename> files.
+	   local <filename>mbox</filename> files, and even NNTP data
+	   (newsgroups), which isn't technically email.
 	 </para>
        </listitem>
      </itemizedlist>
@@ -150,40 +151,68 @@
           message to message.
         </para>
       </sect3>
+      <sect3 id="usage-mail-getnsend-delete">
+        <title>Deleting Mail</title>
+        <para>
+          To delete a message, select it in the the <interface>message
+          list</interface> by clicking on it once.  Then click on the
+          <guibutton>Delete</guibutton> button in the tool bar.  The
+          message now has a line through it, because you've marked it
+          for deletion. 
+        </para>
+        <para>
+          If you really want to get rid of it, choose
+          <guimenuitem>Expunge</guimenuitem> from the
+          <guimenu>Actions</guimenu> menu.  That will delete it
+          permanently. If you want to keep it, click
+          <guibutton>Delete</guibutton> again, and it will no longer
+          be marked as deleted.  At some point in the future, this
+          feature will change to something a little less
+          counter-intuitive.
+        </para>
+      </sect3>
     </sect2>
 
     <sect2 id="usage-mail-getnsend-get">
       <title>Checking Mail</title>
-
       <para>
 	Now that you've had a look around the
-	<interface>Inbox</interface>, select the welcome message in
-	the <interface>message list</interface> by clicking on it
-	once.  Then click on the <guibutton>Delete</guibutton> button
-	in the tool bar.  The message now has a line through it,
-	because you've marked it for deletion.  If you really want to
-	get rid of it, choose <guimenuitem>Expunge</guimenuitem> from
-	the <guimenu>Actions</guimenu> menu.  That will delete it
-	permanently. If you want to keep it, click
-	<guibutton>Delete</guibutton> again, and it will no longer be
-	marked as deleted.  At some point in the future, this feature
-	will change to something a little less counter-intuitive.
+	<interface>Inbox</interface>, it's time to check for new mail.
+	Before you get it, though, you should decide where you want to
+	keep it.  Your options will vary a little depending on your
+	network setup, but they come down to storing the mail on your
+	hard disk (using <glossterm>POP</glossterm>), or storing it on
+	the network (using <glossterm>IMAP</glossterm>).  If you store
+	your mail on your local hard disk, you can read it whether
+	you're online or not, but you can only read it from one
+	computer.  If you store it on the network, you can only read
+	it when you're online, but you can access it from almost any
+	computer with a network connection, even if it doesn't have
+	<application>Evolution</application>.
+      </para>
+      <para>
+        If you choose POP, you'll be putting mail in the
+        <guilabel>Inbox</guilabel> in the <guilabel>Local</guilabel>
+        folder.  If you choose IMAP, it's the
+        <guilabel>Inbox</guilabel> of a folder with the same name as
+        your mail server.  That's so you can maintain several distinct
+        IMAP servers if you want.  See <xref
+        linkend="config-prefs-mail"> for more information about mail
+        servers.
       </para>
-
-
       <para>
-	To check your email, just click <guibutton>Get
-	mail</guibutton> in the toolbar.  If this is the first time
-	you've done so, the <interface>mail setup
+        Regardless of where you keep your mail, you can click
+	<guibutton>Get mail</guibutton> in the toolbar to check your
+	mail.  The first time you do that, the <interface>mail setup
 	assistant</interface> will ask you for the information it
 	needs to check your mail (see <xref
 	linkend="config-setupassist"> for more information).  If
 	you're checking mail over a network (instead of from local
 	<filename>mbox</filename> files), you'll need to enter your
-	email password.  Type it in, click <guibutton>OK</guibutton> and
-	<application>Evolution</application> will download your mail.
-	New mail will appear in your <interface>Inbox</interface>.
-	<!-- FIXME: add mention of Today if Today feature appears -->
+	email password.  Type it in, click <guibutton>OK</guibutton>
+	and <application>Evolution</application> will download your
+	mail.  New mail will appear in your
+	<interface>Inbox</interface>.
       </para>
       <para>
         Once you've entered your password,
@@ -206,6 +235,22 @@
 	linkend="config-prefs-mail-network">, or ask your system
 	administrator.
       </para>
+      
+      <sect3 id="usage-mail-getnsend-get-news">
+         <title>Using Evolution for News </title>
+       <para>
+         Newsgroups are so similar to email there's no reason not to
+         read them side by side.  If you want to do that, add a news
+         source to your configuration (see <xref
+         linkend="config-prefs-network-news">). The news server will
+         appear as a remote server, and will look exactly like an IMAP
+         folder, except that you can't delete messages from it.  When
+         you click <guibutton>Get Mail</guibutton>,
+         <application>Evolution</application> will also check for news
+         messages.  If you prefer to use a different program, there's
+         always <application>Pan</application>.
+       </para>
+       </sect3>
 
       <sect3 id="usage-mail-getnsend-get-attach">
 	<title>Attachments, HTML Mail, and Live Documents</title>
@@ -284,9 +329,9 @@
 	   Evolution will send mail immediately unless you tell it to
 	   do otherwise by selecting <menuchoice>
 	   <guimenu>File</guimenu> <guimenuitem>Send
-	   Later</guimenuitem></menuchoice>.  That will add messages to the
-	   <guilabel>Outbox</guilabel> queue.  Then, when you press
-	   <guibutton>Send</guibutton> in another message, or
+	   Later</guimenuitem></menuchoice>.  That will add messages
+	   to the <guilabel>Outbox</guilabel> queue.  Then, when you
+	   press <guibutton>Send</guibutton> in another message, or
 	   <guibutton>Get Mail</guibutton> in the main mail window,
 	   all your unsent messages will go out at once.  I like to
 	   use "Send Later" because it gives me a chance to change my