Add performance tuning section to manual.

diff --git a/doc/Makefile.am b/doc/Makefile.am
index f97f83e33562b3fb3891ec7d6ff5ce1b1faff54a..efefd32b38c94725546c1a1fb344d7a0f3e3809d 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -28,7 +28,7 @@ EXTRA_DIST = dotlock.man              \
 
 HTML_DOCFILES = manual.html index.html intro.html gettingstarted.html \
        configuration.html mimesupport.html advancedusage.html \
-       reference.html miscellany.html
+       tuning.html reference.html miscellany.html
 
 BUILT_DISTFILES = stamp-doc-xml stamp-doc-chunked manual.txt $(HTML_DOCFILES)
 

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 51645eed1c6de5b1565ed5022fa7aef793c26147..b2ee8886def7cfec80499bdb08224342029eb0f3 100644 (file)
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -4662,7 +4662,7 @@ Details on how to enable either of these techniques are given in the
 following subsections.
 </para>
 
-<sect2>
+<sect2 id="header-caching">
 <title>Header caching</title>
 
 <para>
@@ -4712,7 +4712,7 @@ named <literal>md5</literal>, depending on your operating system.
 
 </sect2>
 
-<sect2>
+<sect2 id="body-caching">
 <title>Body caching</title>
 
 <para>
@@ -5649,6 +5649,75 @@ muttrc.
 
 </chapter>
 
+<chapter id="tuning">
+<title>Performance tuning</title>
+
+<sect1 id="tuning-mailboxes">
+<title>Reading and writing mailboxes</title>
+
+<para>
+Mutt's performance when reading mailboxes can be improved in two ways:
+</para>
+
+<para>
+<orderedlist>
+<listitem><para>
+For remote folders (IMAP and POP) as well as folders using
+one-file-per message storage (Maildir and MH), mutt's
+performance can be greatly improved using
+<link linkend="header-caching">header caching</link>.
+Using a single database per folder may further increase
+performance.
+</para></listitem>
+<listitem><para>
+Mutt provides the <link linkend="read-inc">&dollar;read&lowbar;inc</link>
+and <link linkend="write-inc">&dollar;write&lowbar;inc</link>
+variables to specify at which rate to update progress
+counters. If these values are too low, mutt may spend more
+time on updating the progress counter than it spends on
+actually reading/writing folders.
+</para>
+<para>
+For example, when opening a maildir folder with a few
+thousand messages, the default value for
+<link linkend="read-inc">&dollar;read&lowbar;inc</link>
+may be too low. It can be tuned on on a folder-basis using
+<link linkend="folder-hook">folder-hooks</link>:
+
+<screen>
+# use very high $read_inc to speed up reading hcache'd maildirs
+folder-hook . 'set read_inc=1000'
+# use lower value for reading slower remote IMAP folders
+folder-hook ^imap 'set read_inc=100'
+# use even lower value for reading even slower remote POP folders
+folder-hook ^pop 'set read_inc=1'</screen>
+</para>
+</listitem>
+</orderedlist>
+</para>
+
+</sect1>
+
+<sect1 id="tuning-messages">
+<title>Reading messages from remote folders</title>
+
+<para>
+Reading messages from remote folders such as IMAP an POP can be
+slow especially for large mailboxes since mutt only caches a very
+limited number of recently viewed messages (usually 10) per
+session (so that it will be gone for the next session.)
+</para>
+
+<para>
+To improve performance and permanently cache whole messages,
+please refer to mutt's so-called
+<link linkend="body-caching">body caching</link> for details.
+</para>
+
+</sect1>
+
+</chapter>
+
 <chapter id="reference">
 <title>Reference</title>