Add documentation on how to make EXIT CODE 1 not an error.

Fixes Debian Bug#530749, filed by Reuben Thomas.

svn path=/branches/BRANCH_6-3/; revision=5361

3 files changed, 51 insertions, 7 deletions

diff --git a/NEWS b/NEWS
index c9a6fc0b..a8f1629c 100644
--- a/NEWS
+++ b/NEWS
@@ -123,9 +123,13 @@ fetchmail 6.3.10 (not yet released):
 * A document, README.SSL-SERVER, was added to describe server-side requirements
   for proper SSL and/or TLS service offerings. These are not specific to
   fetchmail.
+* Documentation on how to make "NOMAIL" (exit code 1) not treated an error has
+  been added to the EXIT CODES section of the manpage and to the FAQ as item C8.
+  The suggested solution uses a tiny POSIX shell script fragment.
+  Fixes Debian Bug #530749, filed by Reuben Thomas.
 
 # TRANSLATION UPDATES AND ADDITIONS (ordered by language name):
-* [cs]	  Czech (Petr Pisar)
+* [cs]    Czech (Petr Pisar)
 * [en_GB] English/British
 * [de]    German
 * [id]    Indonesian (Andhika Padmawan)
diff --git a/fetchmail-FAQ.html b/fetchmail-FAQ.html
index a14b2d09..5abc4656 100644
--- a/fetchmail-FAQ.html
+++ b/fetchmail-FAQ.html
@@ -115,8 +115,9 @@ often than others?</a><br/>
 <a href="#C6">C6. Fetchmail works OK started up manually, but not
 from an init script.</a><br/>
 <a href="#C7">C7. How can I forward mail to another
-host?.</a><br/>
-
+host?</a><br/>
+<a href="#C8">C8. Why is "NOMAIL" an error?/I frequently get messages
+from cron!</a><br/>
 
 <h2 id="C_T">How to make fetchmail play nice with various MTAs</h2>
 
@@ -1290,6 +1291,37 @@ host?</a></h2>
 fetchmail on, use the <code>smtphost</code> or
 <code>smtpname</code> option. See the manual page for details.</p>
 
+<h2><a id="C8" name="C8">C8. Why is "NOMAIL" an error?/I frequently get messages
+from cron!</a></h2>
+
+<p>Some users want to write scripts that take action only if mail
+could/could not be retrieved, thus fetchmail reports if it has retrieved
+messages or not.</p>
+
+<p>If you do not want "no mail" to be an error condition (for instance,
+for cron jobs), use a POSIX-compliant shell and add this to the end of
+the fetchmail command line, it will change an exit code of 1 to 0 and
+others to 1:</p>
+<pre>
+|| [ $? -eq 1 ]
+</pre>
+
+<p>If you want to map more than one code to 0, you cannot cascade multiple
+<strong>|| [ $? -eq N ]</strong>, but you must instead use the
+<strong>-o</strong> operator inside the brackets, (see the test(1)
+manpage for details), such as:</p>
+
+<pre>
+|| [ $? -eq 1 -o $? -eq 9 ]
+</pre>
+
+<p>A full cron line might then look like this:</p>
+
+<pre>
+*/15 * * * * fetchmail -s || [ $? -eq 1 ]
+</pre>
+
+
 <hr/>
 <h1>How to make fetchmail play nice with various MTAs</h1>
 <h2><a id="T1" name="T1">T1. How can I use fetchmail with
diff --git a/fetchmail.man b/fetchmail.man
index 0e40521d..b96d2fd6 100644
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -2561,7 +2561,17 @@ One or more messages were successfully retrieved (or, if the \-c option
 was selected, were found waiting but not retrieved).
 .IP 1
 There was no mail awaiting retrieval.  (There may have been old mail still
-on the server but not selected for retrieval.)
+on the server but not selected for retrieval.) If you do not want "no
+mail" to be an error condition (for instance, for cron jobs), use a
+POSIX-compliant shell and add
+
+.nf
+|| [ $? -eq 1 ]
+.fi
+
+to the end of the fetchmail command line, note that this leaves 0
+untouched, maps 1 to 0, and maps all other codes to 1. See also item #C8
+in the FAQ.
 .IP 2
 An error was encountered when attempting to open a socket to retrieve
 mail.  If you don't know what a socket is, don't worry about it --
@@ -2582,9 +2592,7 @@ There was a syntax error in the arguments to
 The run control file had bad permissions.
 .IP 7
 There was an error condition reported by the server.  Can also
-fire if
-\fBfetchmail\fP
-timed out while waiting for the server.
+fire if \fBfetchmail\fP timed out while waiting for the server.
 .IP 8
 Client-side exclusion error.  This means
 \fBfetchmail\fP