From bbd45cd01c5993de0970065b2bbd03aa28837b2c Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Thu, 15 Oct 2020 15:03:14 -0400
Subject: Clarify qpdf's exit statuses in the documentation

---
 TODO                   |  3 +--
 manual/qpdf-manual.xml | 34 ++++++++++++++++++++++++++++++++++
 qpdf/qpdf.cc           |  3 ++-
 3 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/TODO b/TODO
index 63363ab9..9740d8a7 100644
--- a/TODO
+++ b/TODO
@@ -3,14 +3,13 @@ Candidates for upcoming release
 
 * Trivial fixes:
   * Remove travisci
-  * Update manual to clearly state qpdf's exit codes including mention
-    of not exiting with code 1.
 
 * Quick issues:
   * #438: things written to stdout instead of stderr; --no-warn issues
   * #454: integer overflow
   * #451: BufferInputSource performance enhancement
   * #432: WindowsCryptProvider fixes
+  * Add --warning-exit-0 option. Search for --no-warn in the docs.
 
 * Easy build/test
   * #429: cygwin build and openssl version (see #455)
diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index 11e963dc..9579562c 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -594,6 +594,40 @@ make
     Most options require an output file, but some testing or
     inspection commands do not.  These are specifically noted.
    </para>
+   <sect2 id="ref.exit-status">
+    <title>Exit Status</title>
+    <para>
+     The exit status of <command>qpdf</command> may be interpreted as
+     follows:
+     <itemizedlist>
+      <listitem>
+       <para>
+        <literal>0</literal>: no errors or warnings were found. The
+        file may still have problems qpdf can't detect.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <literal>2</literal>: errors were found. qpdf was not able to
+        fully process the file.
+       </para>
+      </listitem>
+      <listitem>
+       <para>
+        <literal>3</literal>: qpdf encountered problems that it was
+        able to recover from. In some cases, the resulting file may
+        still be damaged. Note that qpdf still exits with status
+        <literal>3</literal> if it finds warnings even when
+        <option>--no-warn</option> is specified.
+       </para>
+      </listitem>
+     </itemizedlist>
+     Note that <command>qpdf</command> never exists with status
+     <literal>1</literal>. If you get an exit status of
+     <literal>1</literal>, it was something else, like the shell not
+     being able to find or execute <command>qpdf</command>.
+    </para>
+   </sect2>
   </sect1>
   <sect1 id="ref.shell-completion">
    <title>Shell Completion</title>
diff --git a/qpdf/qpdf.cc b/qpdf/qpdf.cc
index 4e697660..1cfbb04f 100644
--- a/qpdf/qpdf.cc
+++ b/qpdf/qpdf.cc
@@ -1621,7 +1621,8 @@ ArgParser::argHelp()
         << "Ordinarily, qpdf exits with a status of 0 on success or a status of 2\n"
         << "if any errors occurred.  If there were warnings but not errors, qpdf\n"
         << "exits with a status of 3. If warnings would have been issued but --no-warn\n"
-        << "was given, an exit status of 3 is still used.\n";
+        << "was given, an exit status of 3 is still used. qpdf does not use exit\n"
+        << "status 1, since that is used by the shell if it can't execute qpdf.\n";
 }
 
 void
-- 
cgit v1.2.3-54-g00ecf