[PATCH] Add 'tuning' chapter to manual

[Rocco Rutte <pdmef@xxxxxxx>]

Hi,

when thinking about/implementing $search_inc, I recall some discussion 
on #mutt about $read_inc/$write_inc (and now Vincent) noticing that mutt 
may spend more time on updating screen information than on actually 
working.

This patch adds a new "Tuning" chapter to the manual which is supposed 
to be a collection of pointers to other parts of the manual for what 
performance is concerned.

This initial patch only talks about $read_inc/$write_inc and header/body 
caching since these are obvious candidates.

Comments are welcome.

  bye, Rocco
--
:wq!

diff --git a/doc/Makefile.am b/doc/Makefile.am
index ae8708b..19a1531 100644
--- 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 26a4ea6..4d772c9 100644
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -4685,7 +4685,7 @@ Details on how to enable either of these
 following subsections.
 </para>
 
-<sect2>
+<sect2 id="header-caching">
 <title>Header caching</title>
 
 <para>
@@ -4735,7 +4735,7 @@ named <literal>md5</literal>, depending
 
 </sect2>
 
-<sect2>
+<sect2 id="body-caching">
 <title>Body caching</title>
 
 <para>
@@ -5871,6 +5871,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>