Improve documentation for handling multiple folders and new mail detection

diff --git a/ChangeLog b/ChangeLog
index ffb3f809204b3af4e9b25041ded5e57d90aa8a0a..766435011c71236a0a11a9305c3db76834205ecf 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-05-20 17:08 +0200  Paul Walker  <paul@black-sun.demon.co.uk>  (a4d423798321)
+
+       * parse.c: Fix more compiler warnings on amd64 by use of %p instead of
+       %x
+
+2008-05-19 09:52 -0700  Ivan Vilata i Balaguer  <ivan@selidor.net>  (38319cd7d832)
+
+       * ChangeLog, po/ca.po: Updated Catalan translation
+
 2008-05-19 18:49 +0200  Vladimir Marek  <Vladimir.Marek@Sun.COM>  (8ac4b70221ee)
 
        * Makefile.am: Unbreak build with included gettext by explicitly

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index b751aaf0ddcd48a35ce0fa3d940ac21f81cc05f9..d28fba292fa7e7828fc8a603edaf6aeac21f2cb0 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -2523,9 +2523,7 @@ Usage: <literal>&lsqb;un&rsqb;mailboxes</literal> <emphasis>folder</emphasis> &l
 
 <para>
 This command specifies folders which can receive mail and
-which will be checked for new messages.  By default, the
-main menu status bar displays how many of these folders have
-new messages.
+which will be checked for new messages periodically.
 </para>
 
 <para>
@@ -2538,15 +2536,10 @@ respectively.
 </para>
 
 <para>
-When changing folders, pressing <emphasis>space</emphasis> will cycle
-through folders with new mail.
-</para>
-
-<para>
-Pressing TAB in the directory browser will bring up a menu showing the files
-specified by the <literal>mailboxes</literal> command, and indicate which contain new
-messages.  Mutt will automatically enter this mode when invoked from the
-command line with the <literal>-y</literal> option.
+Mutt provides a number of advanced features for handling (possibly many)
+folders and new mail within them, please refer to
+<xref linkend="handling-folders"/> for details (including in what
+situations and how often Mutt checks for new mail).
 </para>
 
 <para>
@@ -2558,27 +2551,30 @@ tokens.
 <para>
 <emphasis role="bold">Note:</emphasis> the folders in the <literal>mailboxes</literal> command are resolved when
 the command is executed, so if these names contain <link linkend="shortcuts">shortcut characters</link> (such as ``='' and ``!''), any variable
-definition that affect these characters (like <link linkend="folder">&dollar;folder</link> and <link linkend="spoolfile">&dollar;spoolfile</link>)
-should be executed before the <literal>mailboxes</literal> command. If
+definition that affects these characters (like <link linkend="folder">&dollar;folder</link> and <link linkend="spoolfile">&dollar;spoolfile</link>)
+should be set before the <literal>mailboxes</literal> command. If
 none of these shorcuts are used, a local path should be absolute as
-otherwise mutt tries to find it within the current working directory
+otherwise mutt tries to find it relative to the directory
 from where mutt was started which may not always be desired.
 </para>
 
 <para>
-For local folders, new mail is detected by comparing access and/or
-modification times of files and folders. The interval in which Mutt
-checks for new mail is defined by
-<link linkend="mail-check">&dollar;mail&lowbar;check</link>.
-</para>
-
-<para>
-Special care is required with Mbox and Mmdf
-folders as Mutt assumes such a folder has new mail if it wasn't
+For Mbox and Mmdf folders, new mail is detected by comparing access and/or
+modification times of files: Mutt assumes a folder has new mail if it wasn't
 accessed after it was last modified. Utilities like <literal>biff</literal> or
 <literal>frm</literal> or any other program which accesses the mailbox might cause
 Mutt to never detect new mail for that mailbox if they do not properly reset the
-access time.  Backup tools are another common reason for updated access times.
+access time. Other possible causes of Mutt not detecting new mail in these folders
+are backup tools (updating access times) or filesystems mounted without
+access time update support.
+</para>
+
+<para>
+In cases where new mail detection for Mbox or Mmdf folders appears to be
+unreliable, the
+<link linkend="check-mbox-size">&dollar;check&lowbar;mbox&lowbar;size</link>
+option can be used to make Mutt track and consult file sizes for new
+mail detection instead.
 </para>
 
 </sect1>
@@ -2635,9 +2631,7 @@ fields, or the fields to remove.  For example, to remove all ``To'' and
 </para>
 
 <para>
-<quote
->unmy&lowbar;hdr to cc</quote
->
+<quote>unmy&lowbar;hdr to cc</quote>
 </para>
 
 </sect1>
@@ -4672,6 +4666,56 @@ uninteresting threads and quickly find topics of value.
 
 </sect1>
 
+<sect1 id="handling-folders">
+<title>Handling multiple folders</title>
+
+<para>
+Mutt supports setups with multiple folders, allowing all of them to
+be monitored for new mail (see <xref linkend="mailboxes"/> for details).
+</para>
+
+<para>
+When in the index menu and being idle (also see
+<link linkend="timeout">&dollar;timeout</link>), Mutt periodically checks
+for new mail in all folders which have been configured via the
+<literal>mailboxes</literal> command. The interval depends on the folder
+type: for local/IMAP folders it consults
+<link linkend="mail-check">&dollar;mail&lowbar;check</link> and
+<link linkend="pop-checkinterval">&dollar;pop&lowbar;checkinterval</link>
+for POP folders.
+</para>
+
+<para>
+Outside the index menu the directory browser supports checking
+for new mail using the <emphasis>check-new</emphasis> function which is
+unbound by default. Pressing TAB will bring up a
+menu showing the files specified by the <literal>mailboxes</literal> command,
+and indicate which contain new messages. Mutt will automatically enter this
+mode when invoked from the command line with the <literal>-y</literal> option.
+</para>
+
+<para>
+For the pager, index and directory browser menus, Mutt contains the
+<emphasis>buffy-list</emphasis> function (bound to ``.'' by default)
+which will print a list of folders with new mail in the command line at
+the bottom of the screen.
+</para>
+
+<para>
+For the index, by default Mutt displays the number of mailboxes with new
+mail in the status bar, please refer to the
+<link linkend="index-format">&dollar;index&lowbar;format</link>
+variable for details.
+</para>
+
+<para>
+When changing folders, Mutt fills the prompt with the first folder from
+the mailboxes list containing new mail (if any), pressing
+<emphasis>space</emphasis> will cycle through folders with new mail.
+</para>
+
+</sect1>
+
 <sect1 id="editing-threads">
 <title>Editing threads</title>
 

diff --git a/init.h b/init.h
index 4333be86c96c573886ffbf60e134276f9394a3bb..ebc625ca3bb7cfbabee3b3007973f58dda2d00b2 100644 (file)
--- a/init.h
+++ b/init.h
@@ -309,7 +309,10 @@ struct option_t MuttVars[] = {
   /*
   ** .pp
   ** When this variable is set, mutt will use file size attribute instead of
-  ** access time when checking for new mail.
+  ** access time when checking for new mail in mbox and mmdf folders.
+  ** .pp
+  ** This variable is \fIunset\fP by default and should only be enabled when
+  ** new mail detection for these folder types is unreliable or doesn't work.
   */
   { "charset",         DT_STR,  R_NONE, UL &Charset, UL 0 },
   /*